---
title: "Upgrade from the Boxever JavaScript Library to the Engage SDK"
slug: "upgrade-from-bx-to-engage-sdk"
abstract: "How to move from an existing, legacy Boxever JavaScript Library integration to a modern integration using the Engage SDK."
---
# Upgrade from the Boxever JavaScript Library to the Engage SDK

If your organization started using Sitecore CDP 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 describes how to:

> [!note]
> **Before you begin**
> -   Have an app that uses the Boxever JavaScript Library.
>
> -   Make sure you're familiar with HTML, JavaScript, and your web browser's developer tools.

## 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:

```javascript
// 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:

```javascript
// 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. Set to `false` if you don't have Personalize. */
    };
    engage = await window.Engage.init(settings);

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

```

Replace the placeholder values with [the required details from your Sitecore CDP instance.](https://doc.sitecore.com/cdp/en/developers/api/integrating-with-sitecore-cdp/preparing-to-integrate/collect-required-details.html "Collect required details")

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 the following to your [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP):
    - Your [Stream API target endpoint](https://doc.sitecore.com/cdp/en/developers/api/integrating-with-sitecore-cdp/walkthroughs-for-integrating/collect-required-details.html#UUID-60c4c930-3cfe-e0ad-3b98-69ceff75989f_section-idm1903325950147122 "Stream API target endpoint").
    - `https://d1mj578wat5n4o.cloudfront.net`
    - If you run web personalization and your environment is **AP Region**, **EU Region**, or **US Region**:

        `https://d35vb5cccm4xzp.cloudfront.net`

    - If you run web personalization and your environment is **JP Region**:

        `https://d2ez8k04aaol9g.cloudfront.net`

- In production, only load the Engage SDK and set cookies if your site visitor grants consent. See also a [code example](https://doc.sitecore.com/cdp/en/developers/api/integrating-with-sitecore-cdp/understanding-integration-details/cookies.html "Cookies") to check if your site visitor accepts cookies.

Learn more about the [`Engage.init()`](https://doc.sitecore.com/cdp/en/developers/api/stream-api/sitecore-engage-sdk-reference/functions/engage-init.html "Engage.init(settings)") function and [the settings object](https://doc.sitecore.com/cdp/en/developers/api/stream-api/sitecore-engage-sdk-reference/objects/settings-object.html "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:

```javascript
_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:

```javascript
// 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](https://doc.sitecore.com/cdp/en/developers/api/stream-api/sitecore-engage-sdk-reference/objects/event-data-object.html "Event data object") 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()`](https://doc.sitecore.com/cdp/en/developers/api/stream-api/sitecore-engage-sdk-reference/functions/engage-pageview.html "Engage.pageView(eventData[, extensionData])").

## 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()`](https://doc.sitecore.com/cdp/en/developers/api/integrating-with-sitecore-cdp/walkthroughs-for-integrating/engage-pageview.html) |
| IDENTITY | [`Engage.identity()`](https://doc.sitecore.com/cdp/en/developers/api/integrating-with-sitecore-cdp/walkthroughs-for-integrating/engage-identity.html) |
| <ul><li>ORDER_CHECKOUT</li><li>ADD</li><li>CONFIRM</li><li>CHECKOUT</li><li>PAYMENT</li><li>CLEAR_CART</li><li>SEARCH</li><li>custom event</li></ul> | [`Engage.event()`](https://doc.sitecore.com/cdp/en/developers/api/integrating-with-sitecore-cdp/walkthroughs-for-integrating/engage-event.html) |

## 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](https://doc.sitecore.com/cdp/en/developers/api/integrating-with-sitecore-cdp/understanding-integration-details/sending-events-using-the-engage-sdk.html "Sending events using the Engage SDK") and [transactional](https://doc.sitecore.com/cdp/en/developers/api/integrating-with-sitecore-cdp/understanding-integration-details/sending-orders-using-the-engage-sdk.html "Sending orders using the Engage SDK") data using the Engage SDK.