Walkthroughs

Integrate using the Engage SDK script

This topic explains how to integrate your website using the Engage SDK.

This walkthrough describes how to:

Before you begin

Collect the required details about your Sitecore Personalize instance.
Make sure you're familiar with HTML, JavaScript, and your web browser's developer tools.
Have a website to integrate.

Load the script on your website

The first step to integrating your website is to load the Engage SDK script on every webpage of your website using the HTML <script> tag.

To load the script:

In your code editor, open the folder structure of your website.
In the folder where you store your JavaScript files, create a new JavaScript file.

Example: scripts/sitecore-engage.js

Open the JavaScript file and paste the following Engage SDK script:

// 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. */
    };
    engage = await window.Engage.init(settings);

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

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

Cookie consent

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.

Content Security Policy (CSP)

To ensure that the Engage SDK script loads, you might have to add the following to your Content Security Policy (CSP):

Your 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

Save the JavaScript file.
Open the HTML file that imports scripts on every webpage of your website.
Import the JavaScript file that contains the script into the HTML file. Import the JavaScript file as the first <script> element before the closing </body> tag.

Important
Depending on the architecture of your website, you might want to place the <script> tag elsewhere in your HTML. Where you import the JavaScript file affects the performance of your web experiences and web experiments.

Example: index.html
<html> <head></head> <body> ... <script src="scripts/sitecore-engage.js"></script> <script></script> <script></script> </body> </html>

Verify that the script loads on your website

To verify that the Engage SDK script loads on your website:

In your web browser, open your website and the console. Keep the website and the console open for the rest of this walkthrough.
In the console, enter engage;.

If an object returns, you have successfully loaded the script on your website.

Send your first VIEW event

After you have verified that the script loads on your website, you collect and send data to Sitecore Personalize. You'll send a VIEW event because the VIEW event triggers every time your webpage loads.

To send a VIEW event:

In your code editor, open the JavaScript file that contains the script.
At the bottom of the s.addEventListener() function, below the engage = await window.Engage.init(settings); line, paste the following code:
// VIEW event object var event = { channel: "<channel_PLACEHOLDER>", language: "<language_PLACEHOLDER>", currency: "<currency_PLACEHOLDER>", page: "<page_PLACEHOLDER>" }; // Send VIEW event engage.pageView(event); // For testing and debugging purposes only console.log("Copy-paste the following line into Sitecore Personalize > Developer center > Event viewer > Search field:"); console.log(engage.getBrowserId());
Replace the placeholder values with the required details from your Sitecore Personalize instance.

This script creates a VIEW event object and sends the event data to Sitecore Personalize immediately after the component renders for the first time. It also logs the browser ID to the console. You'll use the browser ID in the next procedure to find the VIEW event in Sitecore Personalize.
In your web browser, reload the webpage. The VIEW event triggers and the event data is sent.

Verify that Sitecore Personalize captured your VIEW event

After you have sent a VIEW event, you log in to Sitecore Personalize and find the event.

To verify that Sitecore Personalize captured your VIEW event:

In your web browser's console, find a text similar to:

a38b230c-11eb-4cf9-8d5d-274e9f344925
Copy the text.
In Sitecore Personalize, click Developer center > Event viewer, then in the search dropdown, select Browser ID and paste the copied text into the search field. A list of events associated with this guest displays. The list contains a VIEW event. This is the event that was triggered in a previous procedure.

Note
If you have both Sitecore CDP and Sitecore Personalize, you can find the data in Guests.

Next steps

You've now successfully integrated your website with Sitecore Personalize. You sent an event from your website and verified that Sitecore Personalize captures data about your users in real time.

Next, you can:

Send other behavioral data, for example, an IDENTITY event or a custom event.
Send transactional data as the user interacts with products and shopping carts on your site.
Run experiences and experiments.

If you have suggestions for improving this article, let us know!