Upgrade from the Boxever JavaScript Library to the Engage SDK

If your organization started using Sitecore Personalize before March 2023, your app is probably integrated using the Boxever JavaScript Library. The Boxever JavaScript Library is no longer receiving updates, so we recommend that you upgrade to the Engage SDK instead.

This walkthrough assumes that you:

Have an app that uses the Boxever JavaScript Library.
Are familiar with HTML, JavaScript, and your web browser's developer tools.

This walkthrough describes how to:

Update the initializing script.
Update the VIEW event script.
Update the scripts for sending other events.
Update the script for running personalization.

Update the initializing script

To initialize the Engage SDK, replace your existing script for initializing the Boxever JavaScript Library with the new script.

Your existing script for initializing the Boxever JavaScript Library looks similar to:

RequestResponse

// Define the Boxever queue 
var _boxeverq = _boxeverq || [];

// Define the Boxever settings 
var _boxever_settings = {
    client_key: "<client_key_PLACEHOLDER>",
    target: "<stream_api_target_endpoint_PLACEHOLDER>/v1.2",
    cookie_domain: "<cookie_domain_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>",
    web_flow_target: "<web_flow_target_PLACEHOLDER>",
    web_flow_config: { async: false, defer: false },
    javascriptLibraryVersion: "1.4.9"
};

// Load the Boxever JavaScript Library asynchronously 
(function() {
     var s = document.createElement("script");
     s.type = "text/javascript";
     s.async = true;  
     s.src = "https://d1mj578wat5n4o.cloudfront.net/boxever-" + window._boxever_settings.javascriptLibraryVersion + ".min.js";
     var x = document.getElementsByTagName("script")[0]; x.parentNode.insertBefore(s, x);
})();

Here's the new script for initializing the Engage SDK:

RequestResponse

// Initialize the engage variable
var engage = undefined;

// Create and inject the <script> tag into the HTML
var s = document.createElement("script");
s.type = "text/javascript";
s.async = true;
s.src = "https://d1mj578wat5n4o.cloudfront.net/sitecore-engage-v.1.4.3.min.js";
var x = document.querySelector("script");
x.parentNode.insertBefore(s, x);    

// Initialize the Engage SDK
s.addEventListener("load", async () => {
    var settings = {
        clientKey: "<client_key_PLACEHOLDER>",
        targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
        pointOfSale: "<point_of_sale_PLACEHOLDER>",
        cookieDomain: "<cookie_domain_PLACEHOLDER>",
        cookieExpiryDays: 365,
        forceServerCookieMode: false,
        includeUTMParameters: true,
        webPersonalization: true /* boolean or object. See Settings object for all options. Default: false */
    };
    engage = await window.Engage.init(settings);

    // Send a VIEW event
    // ...
});

Replace the placeholder values with the required details from your Sitecore Personalize instance.

Note the following details about the Engage SDK script:

The engage variable is initialized as undefined.
After the <script> tag loads, the asynchronous init() function loads the Engage SDK on your webpages. The engage variable is reassigned to the return value of the init() function.
The settings object has different attributes than _boxever_settings in the Boxever JavaScript Library. For example, client_key is now clientKey and target is now targetURL.
To ensure that the Engage SDK script loads, you might have to add https://d1mj578wat5n4o.cloudfront.net and your Stream API target endpoint to your Content Security Policy (CSP).
In production, only load the Engage SDK and set cookies if your site visitor grants consent. See also a code example to check if your site visitor accepts cookies.

Learn more about the Engage.init() function and the settings object.

Update the VIEW event script

To send VIEW events, replace your existing script for sending VIEW events using the Boxever JavaScript Library with the new script using the Engage SDK.

Your existing script using the Boxever JavaScript Library:

RequestResponse

_boxeverq.push(() => {
    // Create a "VIEW" event object
    var viewEvent = {
        browser_id: Boxever.getID(),
        channel: "<channel_PLACEHOLDER>",
        type: "<type_PLACEHOLDER>",
        language: "<language_PLACEHOLDER>",
        currency: "<currency_PLACEHOLDER>",
        page: "<page_PLACEHOLDER>",
        pos: "<point_of_sale_PLACEHOLDER>"
    };

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

Here's the new script for sending a VIEW event using the Engage SDK. Place this at to the bottom of the s.addEventListener() function, below the engage = await window.Engage.init(settings); line:

RequestResponse

// VIEW event object
var eventData = {
    channel: "<channel_PLACEHOLDER>",
    language: "<language_PLACEHOLDER>",
    currency: "<currency_PLACEHOLDER>",
    page: "<page_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
};

// Send a VIEW event
engage.pageView(eventData);

Replace the placeholder values with event data object values specific to your organization.

Note the following details about the Engage SDK script:

The event object has different attributes than in the Boxever JavaScript Library. browser_id and type are no longer part of the event object. pos is now pointOfSale.
The VIEW event has a dedicated function called Engage.pageView().

Update the scripts for sending other events

In your existing Boxever JavaScript Library script, you're using the Boxever.eventCreate() function to send any type of event. However, in the Engage SDK, some event types have their own function.

To send events, replace your existing Boxever.eventCreate() functions with the applicable function from the following table:

Event type	Function
VIEW	`Engage.pageView()`
IDENTITY	`Engage.identity()`
ORDER_CHECKOUT ADD CONFIRM CHECKOUT PAYMENT CLEAR_CART SEARCH custom event	`Engage.event()`

Update the script for running personalization

In your existing Boxever JavaScript Library script, you're using the Boxever.callFlows() function to run experiences and experiments.

To run personalization using the Engage SDK, use the Engage.personalize() function.

Next steps

You've now successfully upgraded from the Boxever JavaScript Library to the Engage SDK. You initialized the Engage SDK, then updated your scripts for sending events.

Next, you can:

Learn more about sending behavioral and transactional data using the Engage SDK.

Do you have some feedback for us?

If you have suggestions for improving this article,