Skip to main content

Boxever JavaScript Library methods

Abstract

Detailed descriptions of the most commonly used methods available in the Boxever JavaScript Library.

This topic describes in detail the most commonly used methods in the Boxever JavaScript Library.

The following methods are used in production:

The eventCreate() function sends an event to Sitecore CDP. An event is all the data about a user's interaction with your application. Call this function as part of the anonymous function that you add to the _boxeverq array.

Parameters

Parameter

Type

Description

Note

event

object

All the event data.

Specify the browser ID in this object.

Every event that you send to Sitecore CDP must include the browser ID.

callback

function

This callback function handles the response.

N/A

format

string

The format of the response.

Set the value to "json". Other formats are not supported.

Return value

undefined

Example

This example describes how to send a VIEW event to Sitecore CDP. The _boxeverq array receives an anonymous function. The anonymous function contains a VIEW event object. The eventCreate() function receives the VIEW event object and sends the event data to Sitecore CDP.

_boxeverq.push(() => { 
    const viewEvent = { 
        browser_id: Boxever.getID(),
        channel: "WEB",
        type: "VIEW",
        language: "EN",
        currency: "EUR",
        page: "home",
        pos: "myretailsite/ireland",
    };

    // Send the event data to the server
    Boxever.eventCreate(
        viewEvent, 
        response => console.log(response),
        "json"
    );
});

The callFlows() function runs an Interactive Full Stack Experience or an Interactive Full Stack Experiment that is currently live in Sitecore Personalize. You must call this function with the friendlyId of the live experience or experiment that you want to run.

Note

Call this function to run a live Interactive Full Stack Experience or a live Interactive Full Stack Experiment only. Other types of experiences and experiments (Web, Triggered Full Stack) are run by the Boxever JavaScript Library automatically.

You can find the friendlyId in Sitecore Personalize, in a live Interactive Full Stack Experience or Experiment, by clicking Details. The friendlyId is in Setup Details, ID.

Parameters

Parameter

Type

Description

Note

flow

object

Event and experiment data.

Specify the friendlyId in this object.

callback

function

This callback function handles the response.

N/A

Return value

object

Example

In a flow object, specify the friendlyId of the experience or experiment that you want to run, and one guest identifier attribute, for example, the browser ID. Then, pass the object to the callFlows() function:

const flowObject = {
    clientKey: Boxever.getClientKey(),
    friendlyId: "running_shoes_popup_02",
    channel: "WEB",
    language: "EN",
    currencyCode: "EUR",
    pointOfSale: "myretailsite/ireland",
    // guest identifier:
    browserId: Boxever.getID()
};

Boxever.callFlows(
    flowObject,
    response => console.log(response)
);

The rest of the methods are used only for testing and debugging when integrating with Sitecore CDP using the Boxever JavaScript Library.

The addUTMParams() function adds every UTM parameter from the URL of the current webpage to the event object.

Parameters

Parameter

Type

Description

Note

event

object

All the event data.

N/A

Return value

none

Example

The following URL contains UTM parameters:

https://myretailsite.com?utm_source=newsletter&utm_medium=email&utm_campaign=summer_sale&utm_term=running+shoes

By default, the event object does not include UTM parameters. To add the UTM parameters to the event object, pass the event object to the addUTMParams() function:

_boxeverq.push(() => {
    const viewEvent = {...};
    Boxever.addUTMParams(viewEvent); // pass the event object to addUTMParams()
    Boxever.eventCreate(
        viewEvent,
        () => {},
        "json"
    );
});

The event data that is sent to Sitecore CDP now includes all UTM parameters:

{ 
    ...,
    "utm_source":"newsletter",
    "utm_medium":"email",
    "utm_campaign":"summer_sale",
    "utm_term":"running shoes"
}

The browserCreate() function creates a browser ID and a guest reference.

Important

The Boxever JavaScript Library calls this function automatically when no browser ID is found in the cookies or in local storage. We recommend that you do not call this function. To create a browser ID or guest reference manually, use the reset() function instead.

Parameters

Parameter

Type

Description

Note

object

object

An empty object.

N/A

callback

function

This callback function handles the response.

The browser ID is in the ref key of the parameter that is passed to the callback function.

The guest reference is in the customer_ref key of the parameter that is passed to the callback function.

format

string

The format of the response.

Set the value to "json". Other formats are not supported.

Return value

undefined

Example

Call the browserCreate() function. In the callback function, log the response to the console:

Boxever.browserCreate(
    {},
    response => console.log(response),
    "json"
);

The following is logged to the console:

{
    "status": "OK",
    "version": "1.2",
    "client_key": "ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe",
    "ref": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "customer_ref": "f7aabbca-1c1b-4fc2-be72-3e16294a4f03"
}

The ref key contains the browser ID. The customer_ref key contains the guest reference.

The browserShow() function retrieves the guest reference from Sitecore CDP.

The guest reference is in the customer.ref key of the parameter that is passed to the callback function.

Parameters

Parameter

Type

Description

Note

browserId

string

The browser ID.

Set the value to Boxever.browser_id.

clientKey

string

The client key.

Set the value to Boxever.client_key.

Or, to bypass authentication, set the value to 0.

callback

function

This callback function handles the response.

The guest reference is in the customer.ref key of the parameter that is passed to the callback function.

format

string

The format of the response.

Set the value to "json". Other formats are not supported.

Return value

undefined

Example

In the callback function, using the customer.ref key, log the guest reference to the console:

Boxever.browserShow(
    Boxever.browser_id,
    Boxever.client_key,
    response => console.log(response.customer.ref),
    "json"
);

// f7aabbca-1c1b-4fc2-be72-3e16294a4f03

The getBucketNumber() function updates the bucket number cookie in the browser to match the latest bucket number in Sitecore CDP. Call this function after an IDENTITY event triggers. This updates the cookie in the browser to match the bucket number in Sitecore CDP.

Note

This function is specific to Web Experiences and Web Experiments in Sitecore Personalize, and it is only available if you specified web_flow_target when you integrated with Sitecore CDP using the Boxever JavaScript Library.

Parameters

Parameter

Type

Description

Note

[callback]

optional

function

This callback function handles the response.

N/A

Return value

undefined

Example

This example describes how to test that the getBucketNumber() function updates the bucket number cookie in the browser.

First, you get the latest bucket number from Sitecore CDP using the getBucketNumber() function and log the bucket number cookie to the console using the getCookie() function.

Boxever.getBucketNumber(() => console.log(Boxever.getCookie("bx_bucket_number")));
// 49

Then, you call the reset() function to reset the guest reference:

Boxever.reset();

Sitecore CDP creates a new guest reference and assigns a bucket number to this guest. But the bucket number cookie in the browser stays unchanged.

To update the cookie in the browser, you get the latest bucket number from Sitecore CDP again using the getBucketNumber() function. Then, you log the bucket number cookie to the console using the getCookie() function:

Boxever.getBucketNumber(() => console.log(Boxever.getCookie("bx_bucket_number")));
// 21

The bucket number cookie is now different.

The getClientKey() function returns the client key.

Parameters

none

Return value

string

Example

Log the client key to the console:

console.log(Boxever.getClientKey());
// "ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe"

The getCookie() function receives a cookie name and returns the corresponding cookie value.

Note

This function only works for cookies set by the Boxever JavaScript Library and for cookies set using the setCookie() function.

Parameters

Parameter

Type

Description

Note

cookieName

string

The name of the cookie.

N/A

Return value

string

Example

Call the getCookie() function:

console.log(Boxever.getCookie("_example_cookie_name_"));
// "_example_cookie_value_"

The getID() function returns the browser ID.

Every event that you send to Sitecore CDP must include the browser ID.

Use this function in every event object you create and send to Sitecore CDP. See eventCreate().

Parameters

none

Return value

string

Example

Log the browser ID to the console:

console.log(Boxever.getID());
// "a38b230c-11eb-4cf9-8d5d-274e9f344925​"

The reset() function reinitializes the Boxever JavaScript Library. During reinitialization, the function:

  • Clears the event queue.

  • Deletes the browser ID and the guest reference.

  • Reloads the Boxever JavaScript Library. During loading, the Boxever JavaScript Library creates a browser ID and a guest reference.

Parameters

none

Return value

undefined

Example

This example describes how to test that the reset() function deletes, then creates a new browser ID.

console.log(Boxever.getID());
// "a38b230c-11eb-4cf9-8d5d-274e9f344925​"
Boxever.reset();
console.log(Boxever.getID());
// "_a_new_browser_id_"

The setCookie() function creates a cookie in the browser.

Parameters

Parameter

Type

Description

Note

cookieName

string

The name of the cookie.

N/A

cookieValue

string

The value of the cookie.

N/A

[expiresIn]

optional

integer

The number of days before the cookie expires.

If you do not specify this value, the cookie becomes a session cookie.

For example, set the value to 1 for the cookie to expire in 1 day.

Return value

undefined

Example

Create a cookie in the browser that expires in 2 days:

Boxever.setCookie("_example_cookie_name_", "_example_cookie_value_", 2);

The templating() function lets you call HandleBarsJS methods. Call this function to rerender a Web Experience or Web Experiment that is currently live in Sitecore Personalize. The rerendering happens in real time and without further calls to the API that the experience or experiment uses.

Example

Run the Handlebars.compile() method:

Boxever.templating.compile();

The triggerExperiences() function reruns every Web Experience and Web Experiment that is live in Sitecore Personalize.

When the Boxever JavaScript Library loads, it runs every live Web Experience and Web Experiment once. The experiences and experiments do not automatically run again on the same page. You can manually rerun them in response to user input, for example, after the user fills out a form field or clicks a button.

Parameters

none

Return value

undefined

Example

Rerun every live Web Experience and Web Experiment if the user enters a search string that includes the word shoe:

searchBarInput.addEventListener("keyup", event => {
    if (event.target.value.includes("shoe")) {
        Boxever.triggerExperiences();
    }
});