Sitecore Personalize developer documentation

Welcome to the new Sitecore Personalize developer documentation

We updated the Sitecore Personalize developer documentation with the following changes:

  • To align with the business decision to separate the Sitecore CDP and Sitecore Personalize apps, Sitecore CDP developer documentation is no longer published on the same site as Sitecore Personalize developer documentation.

  • We updated code examples with more relevant values.

Your success using this documentation is important to us. Send feedback about the documentation to docsite@sitecore.net.

What's new

The latest updates for Sitecore Personalize APIs.

February 2023

The new Engage JavaScript Library and Engage SDK are modern, easy-to-use tools that help you integrate your application with Sitecore Personalize. The updated Integrating with Sitecore Personalize section describes how to use these tools.

Overview

Sitecore Personalize lets you personalize customer interactions, run experiments, and deliver personalized experiences across all the digital channels of your organization.

The Stream API lets you send real-time behavioral and transactional data about the users of your application to Sitecore Personalize.

Data capturing.

Data models

This documentation describes Sitecore Personalize functionality for two different data models: 2.1 data model and 2.0 data model.

If your organization purchased Sitecore Personalize after March 2021, your instance of Sitecore Personalize is using the 2.1 data model. To use this documentation, make sure that the 2.1 button is selected at the top of the right-hand pane.

If your organization purchased Boxever before 2021, your instance of Sitecore Personalize is probably using the 2.0 data model. To use this documentation, click the 2.0 button at the top of the right-hand pane.

Before you start sending data

Before you start sending data to Sitecore Personalize, you must identify the type of API you want to use and ensure you model the data correctly for the API and data model version of your organization's tenant, 2.1 data model or 2.0 data model.

Sitecore APIs are flexible by-design. To ensure that the data is available for users to leverage in personalization and decisioning, you must follow the data model schema for the specific API.

We recommend that you read the following topics to learn about the APIs and how to model the data:

Sending events

Use the Stream API to collect and send behavioral data to Sitecore Personalize in real time. The behavioral data can include guest's page views, clicks, searches, and identifiers.

Your organization can send additional, custom data with events and use that data in real-time personalization and decisioning.

To ensure that you can access event data in the UI, including custom data, you must model the event object, and the optional event data extensions and custom events, according to your organization's integration:

Sending orders

Sitecore Personalize provides different APIs for sending orders to Sitecore Personalize. The available options depend on different factors including whether orders are submitted in real-time, offline, or synchronously.

This topic provides information on how to model the different order objects depending on the API, integration option, and data model that your organization is using, 2.1 data model or 2.0 data model.

We recommend that you read this topic before you start sending order data, to ensure that users can use the order data in personalization and decisioning. If you do not model the order data correctly, it might not be available in the UI even if you were able to successfully send it to Sitecore Personalize.

Managing orders in real-time

Use the Stream API to collect and send order data in real-time to Sitecore Personalize, including when an order is created. There are several order-related events you can send as a guest interacts with your site, for example, when a guest adds a product to their shopping cart, makes a purchase, or empties their shopping cart.

To ensure that the order is created, you must send the required events, in the correct order, and model the event object based on one of the following integration options:

  • If your organization is using the Engage JavaScript Library or the Engage SDK to integrate, see sending orders for details on the events that are required to create an order. This is the preferred method for sending orders to Sitecore Personalize.

  • If your organization is not using the Engage JavaScript Library or the Engage SDK to integrate, see sending orders for details on the events that are required to create an order.

Stream API

The Stream API lets you send real-time behavioral and transactional data about the users of your application to Sitecore Personalize. Using the Stream API involves integrating your application with Sitecore Personalize.

We recommend that you integrate using the Engage JavaScript Library or the Engage SDK, depending on your business needs.

Overview

Sitecore Personalize provides a suite of API services that makes data management easier, faster, and more efficient. The Stream API captures fast-flowing, high-velocity event data at the same time that it is generated on your organization's website. When you integrate your application using the Engage JavaScript Library or the Engage SDK, the library and the SDK use the Stream API behind the scenes to facilitate the capturing of events. The Stream API can also be deployed in conjunction with your organization's data layer.

The Stream API consists of two APIs. If you integrate your application using direct HTTP requests, you make requests to both of the following APIs:

  • Browser API - the Browser Interface enables you to extend functionality within a web browser or other HTTP client. You can use the Browser Interface to manage cookies in the browser that help identify guests and facilitate personalization.

  • Event API - the Event Interface enables event processing. For example, you can use the Event API to send events in at speed from mobile applications or your website.

The Stream API has the following characteristics:

  • Supports synchronous calls

  • Sends write-only data

  • Processes structured data

  • Captures online events

  • Facilitates Online Data Capture (ODC)

When to use the Stream API

The Stream API provides a light-touch integration that facilitates the immediate realization of Sitecore Personalize functionality. The Stream API is used for the following purposes:

  • Online data capture - you can integrate the Stream API with your data layer to capture guest activity as guests navigate your online booking flow. Sitecore Personalize can also integrate with your website, mobile app, and call center.

  • Website personalization - your organization's web-based application can pass guest, behavioral, and transactional data to Sitecore Personalize to use in real-time decisioning and experience execution.

  • Behavioral information - the Event API captures a guest's behavioral data that can immediately be used in real-time personalization. These are events, for example, the pages the guest visits, the searches the guest performs, purchased products, and products added to the cart but not purchased.

  • Optimizes decisioning - the Stream API captures behavioral and transactional data to ensure that decisioning has the most up-to-date guest, order, and search data for use in personalization and experiments.

Integrating with Sitecore Personalize

Sitecore Personalize captures behavioral and transactional data about users as they interact with an application. To collect this data and send it to Sitecore Personalize, you first have to integrate your app with Sitecore Personalize.

We recommend that you integrate using the Engage JavaScript Library or the Engage SDK, depending on your business needs.

During integration

During integration, you start collecting and sending real-time behavioral and transactional data to Sitecore Personalize using the Stream API:

Data capturing.

For example, the data can include:

  • A user's page views.

  • A user's clicks, searches, and other actions.

  • A user's identifiers when they register or log in.

  • Items the user adds to their shopping cart.

  • Order details.

  • Geolocation details.

After integration

After integrating, Sitecore Personalize starts capturing the behavioral and transactional data from your app. You can then act on that data by:

  • Running experiments to determine which content resonates the most with each user.

  • Personalizing user interactions.

Preparing to integrate

Before you integrate with Sitecore Personalize, you have to:

  • Collect required details about your Sitecore Personalize instance.

  • Choose an integration type.

Collect required details

During integration, you have to provide details about your Sitecore Personalize instance. You should collect the necessary information before you start integrating.

Client key

The client key is your organization's unique and public identifier.

Stream API target endpoint

When you integrate, you send data using the Stream API. Your Stream API target endpoint depends on the environment of your Sitecore Personalize instance.

To find the environment, in Sitecore Personalize, on the navigation pane, click cdp_gear_icon.png > Company information > Environment.

Environment

Stream API target endpoint

AP Region

https://api-engage-ap.sitecorecloud.io​

EU Region

https://api-engage-eu.sitecorecloud.io

US Region

https://api-engage-us.sitecorecloud.io

Name of point of sale

To find the name of your point of sale, in Sitecore Personalize, on the navigation pane, click cdp_gear_icon.png > Points of Sale > Name.

Channel, language, and currency

Channel, language, and currency are part of the data you send.

Parameter

Type

Description

Example

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

For example, for webpages, the channel is WEB. For mobile app screens, the channel is MOBILE_APP.

See the full list of allowed values.

  • EMAIL

  • MOBILE_APP

  • MOBILE_WEB

  • SMS

  • WEB

language

string (uppercase ISO 639-1)

The language the user is using your app in.

For example, if the user selects the Japanese language on your website, the language is JA.

  • DE

  • EN

  • FR

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

For example, if the user selects Australian dollars as the currency on your website, the currency is AUD.

  • EUR

  • GBP

  • USD

Cookie domain (optional)

If you integrate using the Engage JavaScript Library or the Engage SDK, you can specify your cookie domain. The cookie domain is the top-level domain of the website you are integrating. The cookie domain ensures that Sitecore Personalize stores cookies in the web browser as first-party cookies.

Scenario

Example domain

Cookie domain

Integrating the main domain, including all subdomains.

www.myretailsite.com

.myretailsite.com

Integrating a subdomain only.

beta.myretailsite.com

.beta.myretailsite.com

Integrating a website on localhost.

localhost

localhost

Web personalization (optional)

Decide whether you want to run personalization with Sitecore Personalize. This affects how you initialize the Engage JavaScript Library or the Engage SDK.

Choose an integration type

Sitecore Personalize offers various integration options. In general, we recommend that you integrate using either the Engage JavaScript Library or the Engage SDK:

  • The Engage JavaScript Library lets you integrate using a CDN link. Choose the Engage JavaScript Library if your app uses a tag management system (TMS), for example, Google Tag Manager, or if you can load JavaScript files directly on your website.

  • The Engage SDK lets you integrate using a JavaScript package manager, for example, npm. Choose the Engage SDK if you have a modern web development stack, and if you want the option to set cookies from the server and implement server-side tracking.

Before you choose an integration type, consider the following characteristics of the different integration options:

Integration

Characteristics

Client-side integration using the Engage JavaScript Library and a TMS

  • Quick and easy to integrate into existing websites using a CDN link.

  • No website deployment needed.

  • The TMS can control when to load the library script.

  • Supports client-side tracking.

  • The Engage JavaScript Library automatically collects geolocation data.

Client-side integration using the Engage JavaScript Library

Integration using the Engage SDK

  • A modern, easy way to integrate.

  • Supports modern frontend and full stack web technologies, for example, React and Next.

  • Helper functions make it simple to send behavioral and transactional data.

  • Fast and performant.

  • Supports setting cookies from the client and from the server.

  • Supports client-side tracking and server-side tracking.

  • The Engage SDK automatically collects geolocation data.

Server-side integration using direct HTTP requests

  • Language-agnostic integration using API calls.

To choose an integration type, select it from the following table:

Your application

Recommended integration type

  • Web app with TMS

  • Native app with TMS

Client-side integration using the Engage JavaScript Library and Google Tag Manager

Web app without TMS

One of the following:

Native app without TMS

Server-side integration using direct HTTP requests

Hybrid app with both WebView parts and native parts

For the WebView parts, choose the web app integration that you want in this table.

For the native parts, use server-side integration using direct HTTP requests.

Walkthroughs for integrating

When you prepared for integration, you chose an integration type. To start integrating, select the walkthrough for the integration type from the following list:

If you integrated using the Boxever JavaScript Library in the past, we recommend that you upgrade to the Engage JavaScript Library.

Walkthrough: Integrating using the Engage JavaScript Library and Google Tag Manager

This topic walks you through integrating your website using the Engage JavaScript Library and Google Tag Manager (GTM).

This walkthrough assumes that you:

  • Have collected the required details about your Sitecore Personalize instance.

  • Are familiar with Google Tag Manager and have a workspace there to work with.

This walkthrough describes how to:

  • Add a tag for the Engage JavaScript Library to your website.

  • Verify that the library loads on your website.

  • Add more tags to your website.

Add a tag for the Engage JavaScript Library to your website

The first step to integrating your website is to configure and publish a new Google Tag Manager tag for your website. The tag contains the Engage JavaScript Library script and fires when the DOM is ready. The script initializes the Engage JavaScript Library and sends VIEW events from your website.

To add a tag to your website:

  1. In Google Tag Manager, click a container.

  2. In the navigation menu, click Tags > New.

  3. In the upper-left corner of the tag pane, enter a name for your tag, for example, Engage JavaScript Library.

  4. Click the Tag Configuration card.

  5. In the Choose tag type pane, click Custom HTML.

  6. In the HTML code block, paste the following Engage JavaScript Library script:

    <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.3.0.min.js";
        var x = document.querySelector("script");
        x.parentNode.insertBefore(s, x);
    
        // Initialize the Engage JavaScript Library
        s.addEventListener("load", function () {
          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: "<boolean_or_object>"
        };
    
        window.Engage.init(settings).then(function (result) {
          engage = result;
    
          // Send a VIEW event
          var event = {
            channel: "<channel_PLACEHOLDER>",
            language: "<language_PLACEHOLDER>",
            currency: "<currency_PLACEHOLDER>",
            page: "<page_PLACEHOLDER>"
          };
         engage.pageView(event);
        });
      });
    </script>
    

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

  7. Click the Triggering card.

  8. In the Choose a trigger pane, click DOM Ready. Your tag pane now looks similar to this:

    Tag configuration in Google Tag Manager.
  9. In the upper-right corner of the tag pane, click Save.

  10. On the main page, in the upper-right corner of the page, click Submit.

  11. In the Submit Changes pane, in the Version Name field, enter a description, for example, Added Engage JavaScript Library.

  12. Click Publish. Your website now loads the Engage JavaScript Library and sends VIEW events.

Verify that the library loads on your website

After you have added the tag, you can preview your Google Tag Manager container and verify that the tag for the Boxever JavaScript Library fires on your website.

To verify that the library loads on your website:

  1. In Google Tag Manager, click the container that you worked on in the previous procedure.

  2. In the navigation menu, click Tags.

  3. In the upper-right corner, click Preview.

  4. On the Tag Assistant page, enter your website's URL, then click Connect. Your website opens in a new window.

  5. On the Tag Assistant page, find the tag you created in the previous procedure.

    If the tag is listed under Tags Fired, you have successfully loaded the library on your website and sent a VIEW event.

Add more tags to your website

The Engage JavaScript Library now loads on your website, and collects and sends VIEW events. To collect and send other event data, you can add tags to send other events.

Next steps

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

Walkthrough: Integrating using the Engage JavaScript Library

This topic walks you through integrating your website using the Engage JavaScript Library.

This walkthrough assumes that you:

  • Have collected the required details about your Sitecore Personalize instance.

  • Are familiar with HTML, JavaScript, and your web browser's developer tools.

  • Have a website to integrate.

This walkthrough describes how to:

  • Load the library on your website.

  • Verify that the library loads on your website.

  • Send your first VIEW event.

  • Verify that Sitecore Personalize captured your VIEW event.

Load the library on your website

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

To load the library:

  1. In your code editor, open the folder structure of your website.

  2. In the folder where you store your JavaScript files, create a new JavaScript file.

    Example: scripts/sitecore-engage-library.js

  3. Open the JavaScript file and paste the following Engage JavaScript Library 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.3.0.min.js";
    var x = document.querySelector("script");
    x.parentNode.insertBefore(s, x);    
    
    // Initialize the Engage JavaScript Library
    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: "<boolean_or_object>"
        };
        engage = await window.Engage.init(settings);
        
        // Send a VIEW event
        // ...
    });

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

  4. Save the JavaScript file.

  5. Open the HTML file that imports scripts on every webpage of your website.

  6. Import the JavaScript file that contains the library 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

    ...
        <script src="scripts/sitecore-engage-library.js"></script>
        <script></script>
        <script></script>     
      </body>
    </html>

Verify that the library loads on your website

To verify that the library loads on your website:

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

  2. In the console, enter engage;.

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

Send your first VIEW event

After you have verified that the library 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:

  1. In your code editor, open the JavaScript file that contains the library script.

  2. 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("bid:", 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.

  3. 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:

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

    bid: a38b230c-11eb-4cf9-8d5d-274e9f344925​

    Tip

    This text consists of the bid: prefix plus a browser ID.

    In Sitecore Personalize, to find your users by the browser ID, always use the bid: prefix plus the browser ID notation. For example: bid: a38b230c-11eb-4cf9-8d5d-274e9f344925​

  2. Copy the text.

  3. In Sitecore Personalize, click Developer center > Event viewer. 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.

Walkthrough: Integrating a React app using the Engage SDK

This topic walks you through integrating your React app using the Engage SDK.

This walkthrough assumes that you:

This walkthrough describes how to:

  • Install and initialize @sitecore/engage.

  • Send your first VIEW event.

  • Verify that Sitecore Personalize captured your VIEW event.

Install and initialize @sitecore/engage

The first step to integrating your app is to install and initialize the @sitecore/engage package.

To install and initialize the package:

  1. In your terminal, open the root folder of your React app.

  2. Install the Engage SDK by running the following command:

    npm install @sitecore/engage
  3. In your code editor, open the root folder of your React app.

  4. In the src folder, create a file called engage.js.

  5. In engage.js, paste the following code:

    import { init } from "@sitecore/engage";
    
    let engage;
    
    const loadEngage = async () => {
      engage = await init({
        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
      });
    };
    
    loadEngage();
    export { engage };

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

    This script:

    • Imports the init() function from the @sitecore/engage package.

    • Asynchronously loads the Engage API using details about your Sitecore Personalize instance and sets cookies from the client.

    • Exports your instance of the Engage API as a variable called engage.

  6. In App.js, import useEffect from React and engage from engage.js:

    import { useEffect } from "react";
    import { engage } from "./engage.js";

Send your first VIEW event

After you have installed and initialized the @sitecore/engage package, 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:

  1. In App.js, in the App function, call the engage.pageView() function to send VIEW event data:

    import { useEffect } from "react";
    import { engage } from "./engage";
    
    export default function App() {
      useEffect(() => {
        if (engage !== undefined) {
          sendPageViewEvent();
        };
      }, []);
    
      const sendPageViewEvent = async () => {
        const response = await engage.pageView({
          channel: "<channel_PLACEHOLDER>",
          currency: "<currency_PLACEHOLDER>"
        });
    
        // For testing and debugging purposes only
        if (response) {
        console.log("Copy-paste the following line into Sitecore Personalize > Developer center > Event viewer > Search field:");
          console.log("bid:", engage.getBrowserId());
        };
      };
    
      return <></>;
    }
    

    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.

  2. In your terminal, enter npm start to start your React app. When the webpage loads, the VIEW event triggers and the event data is sent.

Verify that Sitecore Personalize captured your VIEW event

Next steps

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

Walkthrough: Integrating a Next app using the Engage SDK (client-set cookies)

This topic walks you through integrating your Next app using the Engage SDK.

In this walkthrough, you'll use client-set cookies.

This walkthrough assumes that you:

This walkthrough describes how to:

  • Install and initialize @sitecore/engage.

  • Send your first VIEW event.

  • Verify that Sitecore Personalize captured your VIEW event.

Install and initialize @sitecore/engage

The first step to integrating your app is to install and initialize the @sitecore/engage package.

To install and initialize the package:

  1. In your terminal, open the root folder of your Next app.

  2. Install the Engage SDK by running the following command:

    npm install @sitecore/engage
  3. In your code editor, open the root folder of your Next app.

  4. In the pages/api folder, create a file called engage.js.

    In engage.js, paste the following code:

    import { init } from "@sitecore/engage";
    
    let engage;
    
    const loadEngage = async () => {
      engage = await init({
        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: "<boolean_or_object>"
      });
    };
    
    loadEngage();
    export { engage };

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

    This script:

    • Imports the init() function from the @sitecore/engage package.

    • Asynchronously loads the Engage API using details about your Sitecore Personalize instance and sets cookies from the client.

    • Exports your instance of the Engage API as a variable called engage.

  5. In the pages folder, in index.js, import useEffect from React and engage from engage.js:

    import { useEffect } from "react";
    import { engage } from "./api/engage.js";

Send your first VIEW event

After you have installed and initialized the @sitecore/engage package, 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:

  1. In index.js, in the Home function, call the engage.pageView() function to send VIEW event data:

    import { useEffect } from "react";
    import { engage } from "./engage";
    
    export default function Home() {
      useEffect(() => {
        if (engage !== undefined) {
          sendPageViewEvent();
        };
      }, []);
    
      const sendPageViewEvent = async () => {
        const response = await engage.pageView({
          channel: "<channel_PLACEHOLDER>",
          currency: "<currency_PLACEHOLDER>"
        });
    
        // For testing and debugging purposes only
        if (response) {
        console.log("Copy-paste the following line into Sitecore Personalize > Developer center > Event viewer > Search field:");
          console.log("bid:", 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.

  2. In your terminal, enter npm run dev to start your Next app. When the webpage loads, the VIEW event triggers and the event data is sent.

Verify that Sitecore Personalize captured your VIEW event

Next steps

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

Walkthrough: Integrating a Next app using the Engage SDK (server-set cookies)

This topic walks you through integrating your Next app using the Engage SDK.

In this walkthrough, you'll use server-set cookies.

This walkthrough assumes that you:

This walkthrough describes how to:

  • Install and initialize @sitecore/engage on the server side.

  • Install and initialize @sitecore/engage on the client side.

  • Send your first VIEW event.

  • Verify that Sitecore Personalize captured your VIEW event.

Install and initialize @sitecore/engage on the server side

The first step to integrating your app is to install and initialize the @sitecore/engage package in your web server. This step involves setting cookies from the server and sending them to the client.

To install and initialize the package on the server side:

  1. In your terminal, open the root folder of your Next app.

  2. Install the Engage SDK by running the following command:

    npm install @sitecore/engage
  3. In your code editor, open the root folder of your Next app.

  4. In the root folder, create a file called middleware.js.

  5. In middleware.js paste the following code:

    import { NextResponse } from 'next/server';
    import { initServer } from '@sitecore/engage';
    
    export async function middleware(request) {
      const response = NextResponse.next();
    
      const engageSettings = {
        clientKey: "<client_key_PLACEHOLDER>",
        targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
        pointOfSale: "<point_of_sale_PLACEHOLDER>",
        cookieDomain: "<cookie_domain_PLACEHOLDER>",
        cookieExpiryDays: 365,
        forceServerCookieMode: true
      };
    
      const engageServer = initServer(engageSettings);
      await engageServer.handleCookie(request, response);
    
      return response;
    };

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

    This script:

    • Initializes the Engage SDK in a middleware function on the server using the initServer() function.

    • Collects the details about your Sitecore Personalize instance and cookie settings in the engageSettings object, and passes the object to the EngageServer.handleEngageCookie() function.

    • Sets cookies from the server.

Install and initialize @sitecore/engage on the client side

The first step to integrating your app is to install and initialize the @sitecore/engage package in your client-side app. This step involves receiving cookies from the server and storing them in the web browser.

To install and initialize the package on the client side:

  1. In the pages folder, in index.js, import useEffect from React and init from @sitecore/engage:

    import { useEffect } from "react";
    import { init } from "@sitecore/engage";
  2. Above the Home() function, create an object called engageSettings:

    const engageSettings = {
      clientKey: "<client_key_PLACEHOLDER>",
      targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
      pointOfSale: "<point_of_sale_PLACEHOLDER>",
      forceServerCookieMode: true,
      includeUTMParameters: true,
      webPersonalization: "<boolean_or_object>"
    };

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

  3. In the Home() function, create an empty, asynchronous function loadEngage(), then call loadEngage() in an Effect Hook. You should use the Effect Hook because the window object has to be present before you load the Engage API. You'll load the Engage API and start sending VIEW events inside loadEngage() in the next procedure.

    export default function Home() {
      const loadEngage = async () => {
        // Load Engage API
        // Send VIEW events
      };
        
      useEffect(() => {
        loadEngage();
      }, []);
    
      return (
        <></>
      );
    };

Send your first VIEW event

After you have installed and initialized the @sitecore/engage package, 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:

  1. In the loadEngage() function, load the Engage API by passing engageSettings to the init() function. The init() function is asynchronous, so you must await the return value.

    const loadEngage = async () => {
      // Load Engage API
      const engage = await init(engageSettings);
    
      // Send VIEW events
    };
    

    In production, you should call the init() function once, then share it across the app using the state management solution of your choice, for example, React Context or Redux.

  2. In the loadEngage() function, after you load the Engage API, call the engage.pageView() function to send VIEW event data:

    const loadEngage = async () => {
      // Load Engage API
      const engage = await init(engageSettings);  
    
      // Send VIEW events
      engage.pageView({
        channel: "<channel_PLACEHOLDER>",
        currency: "<currency_PLACEHOLDER>"
      });
    };
    

    Replace the placeholder values with the event details specific to your organization.

  3. For testing and debugging purposes only, below the engage.pageView() function, log the browser ID to the console:

    const loadEngage = async () => {
      // Load Engage API
      // ...
    
      // Send VIEW events
      // ...
    
      // For testing and debugging purposes only
      console.log("Copy-paste the following line into Sitecore Personalize > Developer center > Event viewer > Search field:");
      console.log("bid:", engage.getBrowserId());
    };
    

    You'll use the browser ID in the next procedure to find the VIEW event in Sitecore Personalize.

  4. In your terminal, enter npm run dev to start your Next app. When the webpage loads, the VIEW event triggers and the event data is sent.

Verify that Sitecore Personalize captured your VIEW event

Next steps

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

Walkthrough: Integrating using direct HTTP requests

This topic walks you through integrating using direct HTTP requests.

This walkthrough assumes that you:

  • Have collected the required details about your Sitecore Personalize instance.

  • Are familiar with the HTTP request-response cycle and with making HTTP requests in the terminal using cURL.

To follow this walkthrough, you'll use a terminal or an API testing tool, for example, Postman. This walkthrough uses cURL in the Git Bash terminal to demonstrate making HTTP requests. In production, you make the HTTP requests in your code base.

This walkthrough describes how to:

  • Get the browser ID from Sitecore Personalize.

  • Send your first VIEW event.

  • Verify that Sitecore Personalize captured your VIEW event.

Get the browser ID from Sitecore Personalize

The first step to integrating is to make an HTTP request to Sitecore Personalize to get the browser ID. You have to include the browser ID in every subsequent request you make to Sitecore Personalize.

To get the browser ID:

  1. In your terminal, make the following HTTP request.

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

    curl -X GET -g '<stream_api_target_endpoint_PLACEHOLDER>/v1.2/browser/create.json?client_key=<client_key_PLACEHOLDER>'

    Example request:

    curl -X GET -g 'https://api.boxever.com/v1.2/browser/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe'

    The HTTP response body is a JSON object that contains a ref key.

    The ref key contains the browser ID.

       "ref" : "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    
  2. Note down the browser ID. You'll include it in every subsequent request you make to Sitecore Personalize.

Send your first VIEW event

After you have retrieved the browser ID, you send an event as key-value pairs.

To send an event:

  1. Prepare the key-value pairs that describe the VIEW event. In a later step, you pass them to the message query parameter in the URL. You must prepare the key-value pairs to be valid in the URL. Make sure that you:

    • Wrap every key and every value in double quotes "".

    • Don't add line breaks.

    • Don't add spaces around keys and around values.

    Example key-value pairs:

    "browser_id":"a38b230c-11eb-4cf9-8d5d-274e9f344925​","channel":"MOBILE_APP","type":"VIEW","language":"EN","currency":"EUR","page":"homepage","pos":"myretailsite/ireland"

    Important

    Note that the "browser_id" key contains the browser ID that you retrieved in a previous step.

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

  2. In your terminal, make the following HTTP request, passing the key-value pairs to the message query parameter.

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

    In the message query parameter, replace the placeholder values with event object values specific to your organization.

    curl -X GET -g '<stream_api_target_endpoint_PLACEHOLDER>/v1.2/event/create.json?client_key=<client_key_PLACEHOLDER>&message={"browser_id":"<browser_id_PLACEHOLDER>","channel":"<channel_PLACEHOLDER>","type":"<type_PLACEHOLDER>","language":"<language_PLACEHOLDER>","currency":"<currency_PLACEHOLDER>","page":"<page_PLACEHOLDER>","pos":"<pos_PLACEHOLDER>"}'

    Example request:

    curl -X GET -g 'https://api.boxever.com/v1.2/event/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe&message={"browser_id":"a38b230c-11eb-4cf9-8d5d-274e9f344925​","channel":"MOBILE_APP","type":"VIEW","language":"EN","currency":"EUR","page":"homepage","pos":"myretailsite/ireland"}'

    The event data is sent to Sitecore Personalize.

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:

  1. In Sitecore Personalize, click Developer center > Event viewer. 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 now successfully integrated your app with Sitecore Personalize. You made an HTTP request to get the browser ID. Then, using the browser ID, you sent a VIEW event and verified that Sitecore Personalize captures data about your users in real time.

Next, you can:

Walkthrough: Upgrading from the Boxever JavaScript Library to the Engage JavaScript Library

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 JavaScript Library 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 library initializing script.

  • Update the VIEW event script.

  • Update the scripts for sending other events.

  • Update the script for running personalization.

Update the library initializing script

To initialize the Engage JavaScript Library:

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

Here's the new script for initializing the Engage JavaScript Library:

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

Note the following details about the Engage JavaScript Library script:

  • The engage variable is initialized as undefined.

  • After the <script> tag loads, the asynchronous init() function loads the Engage JavaScript Library 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.

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 JavaScript Library.

Your existing script using the Boxever JavaScript Library:

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

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

Note the following details about the Engage JavaScript Library 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 JavaScript Library, 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 JavaScript Library:

Next steps

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

Next, you can:

Understanding integration details

This topic describes important concepts and details related to integrating with Sitecore Personalize.

Browser ID

The browser ID is a universally unique identifier (UUID) that Sitecore Personalize assigns to every user of your app. It associates sessions, events, and orders with the respective user.

The browser ID in integrations using the Engage JavaScript Library or the Engage SDK

The Engage JavaScript Library and the Engage SDK automatically create the browser ID. Then, the web browser stores the browser ID as a first-party cookie. The cookie is persisted until it expires or gets deleted.

You can use the Engage.getBrowserId() function to get the browser ID, then find data about the associated user in Sitecore Personalize.

When you send events, the Engage JavaScript Library and the Engage SDK automatically include the browser ID in the event data object.

When you run experiences and experiments without including any optional guest identifier attributes in the personalization data object, the Engage JavaScript Library and the Engage SDK automatically include the browser ID in the personalization data object.

The browser ID in integrations using direct HTTP requests

You have to manually request a browser ID first. To do this, you make a GET request to the Browser API (Stream API type). The response includes the browser ID. In every event that you send to Sitecore Personalize, you have to manually include the browser ID.

The browser ID in Sitecore Personalize

If you know the browser ID for a user of your app, you can use the browser ID to find data about the user in Sitecore Personalize.

Then, Sitecore Personalize lists the guest profile for the user. In the guest profile, you can find session, event, and order data about your user.

Geolocation data

The Engage JavaScript Library and the Engage SDK automatically collect geolocation data about the users of your app. The geolocation data includes city, country, and continent information based on the user's IP address.

Cookies in the Engage SDK

Sitecore Personalize stores cookies in the web browser as first-party cookies. First-party cookies are cookies set by the domain that appears in the web browser's address bar.

The Engage SDK supports setting cookies from the client and from the server.

Client-set cookies

If you can access only the client side of your app, you have to set cookies from the client.

You can set cookies from the client by setting the forceServerCookieMode attribute to false in the settings object, then passing the settings object to the Engage.init() function. For code samples, see Integrating a React app and Integrating a Next app (client-set cookies).

Server-set cookies

If you can access the server side of your app, you can choose to set cookies from the server instead of the client. In that scenario, you create and manage cookies on your web server. Then, the web server sends the cookies to the client app. Finally, the client app stores the cookie in the web browser.

Setting cookies from the server has the following benefits:

  • Increases security by adding the httpOnly attribute to cookies. This helps prevent client-side JavaScript from accessing the cookies and mitigate cross-site scripting (XSS) attacks.

  • Mitigates the impact of Intelligent Tracking Prevention (ITP) on cookies. For example, unlike client-set cookies, server-set cookies don't expire automatically after 7 days.

Using the Engage SDK, you can set cookies from the server by setting the forceServerCookieMode attribute to true in the settings object, then passing the settings object to the Engage.init() function on the client side, and to the Engage.initServer() function on the server side. For code samples, see Integrating a Next app (server-set cookies).

Sending events using the Engage JavaScript Library or the Engage SDK

Using the Engage JavaScript Library or the Engage SDK, you can collect and send behavioral data to Sitecore Personalize in real time. The behavioral data includes, for example, the user's page views, clicks, searches, and identifiers as they register or log in.

To collect and send behavioral data in real time, you send events to Sitecore Personalize using either client-side tracking or server-side tracking. The Engage JavaScript Library supports client-side tracking. The Engage SDK supports both client-side tracking and server-side tracking.

You can send the following events:

To collect and send transactional data about a user's cart activity and orders, see sending orders.

Sending orders using the Engage JavaScript Library or the Engage SDK

Using the Engage JavaScript Library or the Engage SDK, you can collect and send transactional data to Sitecore Personalize in real time.

You collect and send transactional data in the same way as you collect and send behavioral data, using either client-side tracking or server-side tracking. The Engage JavaScript Library supports client-side tracking. The Engage SDK supports both client-side tracking and server-side tracking.

The transactional data includes orders that the user makes as they interact with your app. You can send an order to Sitecore Personalize in real time using either a single event or multiple events.

Sending orders using a single event

Use this option if your organization's site is tagged to send all order-related data from the confirmation page. You can also use this option if your organization uses an order management system (OMS), or if your organization uses cookies and local storage to capture order details.

To send an order to Sitecore Personalize in real time using a single event, you must use the Engage.event() function (client-side tracking) or the EngageServer.event() function (server-side tracking) to send an ORDER_CHECKOUT event.

Sending orders using multiple events

Use this option if the booking flow for your organization's site does not facilitate sending all order-related data from the confirmation page. This way, you can send individual events related to orders when, for example, a user adds a product to their shopping cart, makes a purchase, or empties their shopping cart.

To send an order to Sitecore Personalize in real time using multiple events, you must use the Engage.event() function (client-side tracking) or the EngageServer.event() function (server-side tracking) to send the following events in this sequence:

  1. ADD event - to capture the product details when a user adds a product to their cart.

  2. CONFIRM event - to capture a list of products that are in the cart before the payment is made.

  3. One of the following:

    • CHECKOUT event - to capture a user's action of completing a purchase.

      • Optionally, after a CHECKOUT event, a PAYMENT event - to capture the user's payment method.

    • CLEAR_CART event - to capture the user's action of emptying their cart.

See all options for sending orders to Sitecore Personalize.

Server-side tracking with the Engage SDK

If you can access the server side of your app, you can use the Engage SDK to implement server-side tracking instead of client-side tracking.

Client-side tracking means that you send behavioral and transactional data from the client side of your app directly to Sitecore Personalize.

In contrast, server-side tracking means that you send the data from the client to the server first. Then, you forward the data from the server to Sitecore Personalize.

Benefits of server-side tracking

Compared to client-side tracking, server-side tracking has the following benefits:

  • Increases data security - you can handle sensitive data on the server without having to expose it on the client side.

  • Increases data flexibility - on the server, you can extend the data, integrate it with other external systems, or otherwise customize it before forwarding it to Sitecore Personalize.

  • Prevents ad blockers and web browsers from blocking the tracking code or otherwise manipulating the data.

  • Improves website performance by reducing the number of network requests to external systems. This improves website speed and ensures that data is captured even on poor network connections.

Considerations before implementing server-side tracking

Before you implement server-side tracking, make sure that your server-side infrastructure is secure, and that you handle data in compliance with privacy regulations.

Implementing server-side tracking

Using the Engage SDK, you can implement server-side tracking by initializing the Engage SDK on the server side of your app, then sending events using the server-side tracking functions.

Queueing events using the Engage JavaScript Library or the Engage SDK

Using the Engage JavaScript Library or the Engage SDK, you can collect events and send them later in one go. This is useful when, for example, you want to conditionally chain different events depending on which actions your user takes.

To collect events, you can use the event queue. The event queue is a first-in, first-out array stored in session storage in the EngageEventQueue key. You can add any event with a valid payload to the event queue.

Important

The event queue requires that session storage is enabled. Because users can disable session storage, you should use try-catch blocks to handle errors when you're interacting with the event queue.

To interact with the event queue, you can use the following functions:

Viewing events in Sitecore Personalize

After integrating, Sitecore Personalize starts capturing the behavioral and transactional data from your app.

Running personalization

Running interactive full stack experiences and experiments

You can run interactive full stack experiences and experiments by using the Engage.personalize() function (client-side tracking) or the EngageServer.personalize() function (server-side tracking).

Running web experiences and web experiments

While you're initializing the Engage JavaScript Library or the Engage SDK, you can decide whether to run web experiences and web experiments in your app. You can run web experiences and web experiments by setting the webPersonalization attribute to true in the settings object in the Engage.init() function, on the client side of your app. This attribute is not available on the server side.

Rerunning web experiences and web experiments

When the Engage functionality first loads in your app with the webPersonalization attribute set to true in the settings object, web experiences and web experiments run once. The experiences and experiments don't automatically run again on the same page. This means that you'll need to rerun experiences and experiments in, for example, the following scenarios:

  • You want to run personalization multiple times on the same page, for example, after the user fills out a form field or clicks a button.

  • You have a single-page application (SPA), which consists of only one web document, and you want to run personalization when the user navigates between routes.

Using the Engage JavaScript Library and the Engage SDK, you can rerun web experiences and web experiments by using the Engage.triggerExperiences() function.

Behavioral and transactional data in personalized content

Using the Engage JavaScript Library or the Engage SDK, you can collect and send behavioral and transactional data that occur inside a web experience or a web experiment. To achieve this, you need to call Engage functions inside your web experience or web experiment.

If you integrate using the Engage JavaScript Library, you can call, for example, the Engage.pageView() function inside your web experience or web experiment.

If you integrate using the Engage SDK, you first need to expose the Engage functions to the window object. You can expose them by assigning the return value of the Engage.init() function to a new property on the window object. For example, you can assign the return value to window.Engage.exposedFunctions. You can then call, for example, the Engage.exposedFunctions.pageView() function inside your web experience or web experiment.

Finding the Sitecore Engage version number

After you load the Engage JavaScript Library or initialize the Engage SDK on your website, you can check which version of Sitecore Engage your website is using.

Regardless of how you integrated, the easiest way you can find the Sitecore Engage version number is to inspect the network requests that your website makes. You can do this by opening your web browser's developer tools, then navigating to your website. In the developer tools, on the Network tab, click one of the events you sent. Every event request is called events. In events, the version number is in Headers > Request Headers > x-library-version.

The version number displayed in the request header.

Depending on how you integrated, there are also alternative ways you can find the Sitecore Engage version number.

You can find the version number by opening your web browser's developer tools, then navigating to your website, then doing one of the following:

  • On the Console tab, log engage.version to the console. The version number is returned.

  • In the HTML tree (usually on the Elements tab or Inspector tab), search for sitecore-engage-v.. This will find a <script> tag with a src attribute similar to https://d1mj578wat5n4o.cloudfront.net/sitecore-engage-v.1.3.0.min.js.

    The version number is the numbers that follow sitecore-engage-v., for example, 1.3.0.

If you can access the source code of your website, you can find the version number in package.json > dependencies > @sitecore/engage.

If you exposed Engage functionality to the window object, you can find the version number by opening your web browser's developer tools, then navigating to your website, then logging window.Engage.version; to the console. The version number is returned.

Engage JavaScript Library and Engage SDK reference

Using the Engage JavaScript Library or the Engage SDK is the recommended way to integrate your app with Sitecore Personalize.

This section describes the most commonly used functions and objects, how to troubleshoot common errors, and release notes for the Engage JavaScript Library and the Engage SDK.

Functions

If you integrate with Sitecore Personalize using the Engage JavaScript Library or the Engage SDK, use this reference for creating your functions.

Engage.init(settings)

The asynchronous init() function initializes the Engage JavaScript Library or the Engage SDK on the client side of your app. Call this function after the window object is defined and before you call any other Engage functions.

During initialization, the function creates a browser ID and stores it as a cookie in the browser.

Parameters

Parameter

Type

Description

settings

object

Details about your Sitecore Personalize instance and cookie settings.

Example 1. Example: Engage JavaScript Library

Here's an example of how to use the init() function. You must call the init() function asynchronously and save the return value into a variable.

// 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.3.0.min.js";
var x = document.querySelector("script");
x.parentNode.insertBefore(s, x);    

// Initialize the Engage JavaScript Library
s.addEventListener("load", async () => {
    const 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: "<boolean_or_object>"
    };
    engage = await window.Engage.init(settings);
});
// 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.3.0.min.js";
var x = document.querySelector("script");
x.parentNode.insertBefore(s, x);    

// Initialize the Engage JavaScript Library
s.addEventListener("load", async () => {
    const 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: "<boolean_or_object>"
    };
    engage = await window.Engage.init(settings);
});
Example 2. Example: Engage SDK

Here's an example of how to use the init() function in a React app. You must call the init() function asynchronously and save the return value into a variable.

You can expose Engage functions to the window object by assigning the return value to a new property on the window object. You must do this in order to call Engage functions inside your web experience or web experiment in Sitecore Personalize.

In production, you should call the init() function once, then share it across the app using the state management solution of your choice, for example, React Context or Redux.

engage.js:

import { init } from "@sitecore/engage";

let engage;

const loadEngage = async () => {
  engage = await init({
    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: "<boolean_or_object>"
  });

  // Expose Engage functions to the window object:
  window.Engage.exposedFunctions = engage;
};

loadEngage();
export { engage };
import { init } from "@sitecore/engage";

let engage;

const loadEngage = async () => {
  engage = await init({
    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: "<boolean_or_object>"
  });

  // Expose Engage functions to the window object:
  window.Engage.exposedFunctions  = engage;
};

loadEngage();
export { engage };

App.js:

import { useEffect } from "react";
import { engage } from "./engage.js";

export default function App() {
    useEffect(() => {
    if (engage !== undefined) {
        // Send VIEW event
    };
    }, []);
// ...
}
import { useEffect } from "react";
import { engage } from "./engage.js";

export default function App() {
    useEffect(() => {
    if (engage !== undefined) {
        // Send VIEW event
    };
    }, []);
// ...
}

Engage.initServer(settings)

The initServer() function initializes the Engage SDK on the server side of your app. This function returns an object that contains the initServer.handleCookie() function. After you call the initServer() function, you must call the init() function on the client side of your app.

You pass the same settings object to both initServer() and init(), except that you don't specify the webPersonalization attribute in initServer(). That’s because the webPersonalization() attribute is only available on the client side.

Parameters

Parameter

Type

Description

settings

object

Details about your Sitecore Personalize instance and cookie settings.

Example 3. Next app

Here's an example of how to use the initServer() function in a Next app. You must call the initServer() function and save the return value into a variable.

pages/index.js:

import { useEffect } from "react";
import { init, initServer } from "@sitecore/engage";

const engageSettings = {
    // ...
    forceServerCookieMode: true
};

const engageServer = initServer(engageSettings);

export async function getServerSideProps({ req, res }) {
  await engageServer.handleCookie(req, res);
  return {
    props: {},
  };
};

export default function Home() {
  // ...
};
import { useEffect } from "react";
import { init, initServer } from "@sitecore/engage";

const engageSettings = {
    // ...
    forceServerCookieMode: true
};

const engageServer = initServer(engageSettings);

export async function getServerSideProps({ req, res }) {
  await engageServer.handleCookie(req, res);
  return {
    props: {},
  };
};

export default function Home() {
  // ...
};

Note the following about the script:

  • In the settings object, forceServerCookieMode is set to true. This ensures that cookies are set from the server.

  • The engageServer variable is assigned to the return value of the initServer() function. That gives engageServer access to the handleCookie() function.

  • The handleCookie() function creates cookies on the server and includes them in the response header.

Here's an example of how to receive the cookie from the server in a Next app and store the cookie in the web browser.

pages/index.js:

export default function Home() {
  const loadEngage = async () => {
    // Load Engage API
    const engage = await init({...engageSettings, webPersonalization: "<boolean_or_object>"});

    // Send VIEW events
  };
    
  useEffect(() => {
    loadEngage();
  }, []);

  return (
    <></>
  );
};
export default function Home() {
  const loadEngage = async () => {
    // Load Engage API
    const engage = await init({...engageSettings, webPersonalization: "<boolean_or_object>"});

    // Send VIEW events
  };
    
  useEffect(() => {
    loadEngage();
  }, []);

  return (
    <></>
  );
};

In this script, the same settings object is passed to the init() function that was passed to the initServer() function on the server side, except that the webPersonalization attribute is specified only on the client side.

The client receives the header from the server and stores the cookie in the web browser.

Engage.initServer.handleCookie(req, res)

The asynchronous initServer.handleCookie() function creates the browser ID cookie on the server side and includes the cookie in the response header. To access this function, you must first call the initServer() function. After you call initServer.handleCookie(), you receive the cookie on the client side in the response header.

Tip

In production, we recommend that you call the initServer.handleCookie() function in a middleware.

Parameters

Parameter

Type

Description

req

object

The HTTP request.

res

object

The HTTP response.

Example 4. Next app

Here's an example of how to use the initServer.handleCookie() function in a Next app to set cookies from the server.

To set cookies from the server, you must set the forceServerCookieMode attribute to true in the settings object. After you call the initServer.handleCookie() function, the cookie is set in the response header.

import { initServer } from "@sitecore/engage";

const engageSettings = {
    // ...
    includeUTMParameters: true
};

const engageServer = initServer(engageSettings);

export async function getServerSideProps({ req, res }) {
  await engageServer.handleCookie(req, res);
  return {
    props: {},
  };
};

export default function Home() {
  // ...
};
import { initServer } from "@sitecore/engage";

const engageSettings = {
    // ...
    includeUTMParameters: true
};

const engageServer = initServer(engageSettings);

export async function getServerSideProps({ req, res }) {
  await engageServer.handleCookie(req, res);
  return {
    props: {},
  };
};

export default function Home() {
  // ...
};

Engage.getBrowserId()

The getBrowserId() function returns the browser ID. This function is used for testing and debugging purposes.

Parameters

none

Log the browser ID to the console:

console.log("bid:", engage.getBrowserId());
// "bid: a38b230c-11eb-4cf9-8d5d-274e9f344925​"
console.log("bid:", engage.getBrowserId());
// "bid: a38b230c-11eb-4cf9-8d5d-274e9f344925​"

You can use the string that was logged to the console to find data about a specific user in Sitecore Personalize.

Engage.getGuestId()

The getGuestId() function returns the guest reference.

Parameters

none

Log the guest reference to the console:

console.log(engage.getGuestId());
// "f7aabbca-1c1b-4fc2-be72-3e16294a4f03"
console.log(engage.getGuestId());
// "f7aabbca-1c1b-4fc2-be72-3e16294a4f03"

Engage.updatePointOfSale(pointOfSale)

The updatePointOfSale() function updates the value of pointOfSale that you previously specified in the settings object. Then, every event that you send inside the scope of this function will automatically include the updated point of sale.

Parameters

Parameter

Type

Description

pointOfSale

string

The new point of sale.

You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize.

Here's an example of a scenario where an organization uses multiple points of sale. The default point of sale is specified as "myretailsite" in the settings object. If certain conditions are met, the point of sale is updated to "myretailsite/europe". Then, a VIEW event is sent with the new point of sale.

import { init } from "@sitecore/engage";

const loadEngage = async () => {
  const engage = await init({
      // ...
      pointOfSale: "myretailsite"
  });

  if (region === "europe") {
      engage.updatePointOfSale("myretailsite/europe");
      engage.pageView({
          // ...
      });
  };
};
import { init } from "@sitecore/engage";

const loadEngage = async () => {
  const engage = await init({
      // ...
      pointOfSale: "myretailsite"
  });

  if (region === "europe") {
      engage.updatePointOfSale("myretailsite/europe");
      engage.pageView({
          // ...
      });
  };
};

Engage.pageView(eventData[, extensionData])

Note

This is a client-side function used for implementing client-side tracking. If you want to implement server-side tracking instead, use the server-side functions.

The pageView() function sends a VIEW event. The VIEW event triggers every time your webpage loads. You should send a VIEW event from every webpage that you want to track on your website.

Parameters

Parameter

Type

Description

eventData

object

All the event data.

[extensionData]

optional

object

Maximum 50 custom attributes of your choice.

Here's an example of how to use the pageView() function. In a React app, call this function in an Effect Hook.

import { engage } from "./engage.js";
// ...

useEffect(() => {
  if (engage !== undefined) {
      sendPageViewEvent();
  };
}, []);

const sendPageViewEvent = async () => {
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    pageVariantId: "351"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engage.pageView(eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

useEffect(() => {
  if (engage !== undefined) {
      sendPageViewEvent();
  };
}, []);

const sendPageViewEvent = async () => {
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    pageVariantId: "351"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engage.pageView(eventData, extensionData);
};

Engage.identity(eventData[, extensionData])

The identity() function sends an IDENTITY event. The IDENTITY event is used to resolve the identity of an anonymous user of your app and turn them into a known user.

Parameters

Parameter

Type

Description

eventData

object

All the event data.

[extensionData]

optional

object

Maximum 50 custom attributes of your choice.

Here's an example of how to use the identity() function to send the email address that a user enters in a form. In a React app, you can capture form data using the State Hook.

components/Form.jsx:

import { useState } from "react";
import { engage } from "../engage";

export default function Form() {
    const [email, setEmail] = useState("");

    const handleEmail = (e) => {
        setEmail(e.target.value);
    };

    const handleSubmit = async (e) => {
        e.preventDefault();

        const eventData = {
          channel: "WEB",
          currency: "EUR",
          pointOfSale: "myretailsite/ireland",
          language: "EN",
          page: "home",
          email,
          identifiers: [
              {
                  id: "123456",
                  provider: "BXLP"
              }
          ]
        };

        const extensionData = {
          customKey: "customValue"
        };
        
        // Send IDENTITY event to Sitecore Personalize
        await engage.identity(eventData, extensionData);
    };

    return (
        <form onSubmit={handleSubmit}>
            <label>
                <span>Email:</span>
                <input type="text" onChange={handleEmail} value={email} />
            </label>

            <button>Subscribe</button>
        </form>
    )
};
import { useState } from "react";
import { engage } from "../engage";

export default function Form() {
    const [email, setEmail] = useState("");

    const handleEmail = (e) => {
        setEmail(e.target.value);
    };

    const handleSubmit = async (e) => {
        e.preventDefault();

        const eventData = {
          channel: "WEB",
          currency: "EUR",
          pointOfSale: "myretailsite/ireland",
          language: "EN",
          page: "home",
          email,
          identifiers: [
              {
                  id: "123456",
                  provider: "BXLP"
              }
          ]
        };

        const extensionData = {
          customKey: "customValue"
        };
        
        // Send IDENTITY event to Sitecore Personalize
        await engage.identity(eventData, extensionData);
    };

    return (
        <form onSubmit={handleSubmit}>
            <label>
                <span>Email:</span>
                <input type="text" onChange={handleEmail} value={email} />
            </label>

            <button>Subscribe</button>
        </form>
    )
};

Engage.event(type, eventData[, extensionData])

The event() function sends one of the following:

Parameters for a standard event

Parameter

Type

Description

type

string

The type of the standard event. If you set this value to any of the Sitecore Personalize reserved event names, for example, VIEW, ADD, or CONFIRM, the event becomes a standard event.

Sitecore Personalize reserved event names:

eventData

object

All the event data specific to the standard event type, for example, an ADD event.

[extensionData]

optional

object

Maximum 50 custom attributes of your choice.

Parameters for a custom event

Parameter

Type

Description

type

string

The name of the custom event. If you set this value to a custom value of your choice different than Sitecore Personalize reserved event names, for example, CUSTOM_EVENT_SEARCH or myretailsite:CLICKED_POPUP, the event becomes a custom event.

eventData

object

The required attributes that every event object must include, and optional attributes that event objects can include.

[extensionData]

optional

object

Maximum 50 custom attributes of your choice.

Example 5. ORDER_CHECKOUT event

Here's an example of how to use the event() function to send an ORDER_CHECKOUT event. The eventData object must contain all the required attributes for the event type, in this example, for an ORDER_CHECKOUT event.

import { engage } from "./engage.js";
// ...

const handleOrderCheckoutEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "checkout page",
      order: {
        referenceId: "123456",
        orderedAt: "2023-08-23T16:17:16.000Z",
        status: "PURCHASED",
        currencyCode: "EUR",
        price: 200,
        paymentType: "Card",
        cardType: "Visa",
        extensions: [ 
           {
              name: "ext",
              key: "default",
              refundable: true
           }
        ],
        orderItems: [
           {
              type: "MOBILE_PHONE",
              referenceId: "REF-123",
              orderedAt: "2023-08-23T16:17:16.000Z",
              status: "PURCHASED",
              currencyCode: "EUR",
              price: 200,
              name: "Mobile phone of type x",
              productId: "MOBILE_PHONE_TYPE_X",
              quantity: 1,
              extensions: [
                 {
                    name: "ext",
                    key: "default",
                    phoneColor: "Gold",
                    insurance: false
                 }
              ]
           }
        ]
     }
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("ORDER_CHECKOUT", eventData, extensionData);
};
Example 6. ADD event

Here's an example of how to use the event() function to send an ADD event. The eventData object must contain all the required attributes for the event type, in this example, for an ADD event.

import { engage } from "./engage.js";
// ...

const handleClickAddEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "products",
      product: {
          name: "GHT 84 Lace Sneaker",
          type: "FOOTWEAR",
          item_id: "SHOES_8475GHT",
          productId: "example_product_id",
          referenceId: "MA-490094",
          orderedAt: new Date().toISOString(),
          quantity: 1,
          price: 7.99,
          currency: "EUR",
          originalPrice: 7.79,
          originalCurrencyCode: "USD"
      }
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("ADD", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

const handleClickAddEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "products",
      product: {
          name: "GHT 84 Lace Sneaker",
          type: "FOOTWEAR",
          item_id: "SHOES_8475GHT",
          productId: "example_product_id",
          referenceId: "MA-490094",
          orderedAt: new Date().toISOString(),
          quantity: 1,
          price: 7.99,
          currency: "EUR",
          originalPrice: 7.79,
          originalCurrencyCode: "USD"
      }
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("ADD", eventData, extensionData);
};
Example 7. CONFIRM event

Here's an example of how to use the event() function to send a CONFIRM event. The eventData object must contain all the required attributes for the event type, in this example, for a CONFIRM event.

import { engage } from "./engage.js";
// ...

const handleClickConfirmEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "checkout",
      product: [
        { item_id: "SHOES_8475GHT" }
      ]
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("CONFIRM", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

const handleClickConfirmEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "checkout",
      product: [
        { item_id: "SHOES_8475GHT" }
      ]
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("CONFIRM", eventData, extensionData);
};
Example 8. CHECKOUT event

Here's an example of how to use the event() function to send a CHECKOUT event. The eventData object must contain all the required attributes for the event type, in this example, for a CHECKOUT event.

import { engage } from "./engage.js";
// ...

const handleClickCheckoutEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home",
      reference_id: "MA-490094",
      status: "PURCHASED"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("CHECKOUT", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

const handleClickCheckoutEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home",
      reference_id: "MA-490094",
      status: "PURCHASED"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("CHECKOUT", eventData, extensionData);
};
Example 9. PAYMENT event

Here's an example of how to use the event() function to send a PAYMENT event. The eventData object must contain all the required attributes for the event type, in this example, for a PAYMENT event.

import { engage } from "./engage.js";
// ...

const handleClickPaymentEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home",
      paymentType: "voucher"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("PAYMENT", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

const handleClickPaymentEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home",
      paymentType: "voucher"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("PAYMENT", eventData, extensionData);
};
Example 10. CLEAR_CART event

Here's an example of how to use the event() function to send a CLEAR_CART event. The eventData object must contain all the required attributes for the event type, in this example, for a CLEAR_CART event.

import { engage } from "./engage.js";
// ...

const handleClickClearCartEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("CLEAR_CART", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

const handleClickClearCartEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("CLEAR_CART", eventData, extensionData);
};
Example 11. SEARCH event

Here's an example of how to use the event() function to send a SEARCH event. The eventData object must contain all the required attributes for the event type, in this example, for a SEARCH event.

import { engage } from "./engage.js";
// ...

const handleSearchEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "search result page",
      "product_name": "airSupport",
      "product_type": "RUNNERS"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("SEARCH", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

const handleSearchEvent = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "search result page",
      "product_name": "airSupport",
      "product_type": "RUNNERS"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("SEARCH", eventData, extensionData);
};
Example 12. Custom event

Here's an example of how to use the event() function to send a custom event called myretailsite:CLICKED_POPUP. eventData contains all the required attributes for the event data object. extensionData contains the custom data.

import { engage } from "./engage.js";
// ...

const handleClick = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("myretailsite:CLICKED_POPUP", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

const handleClick = async () => {
    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("myretailsite:CLICKED_POPUP", eventData, extensionData);
};

Engage.addToEventQueue(type, eventData[, extensionData])

The addToEventQueue() function saves any event with a valid payload to the event queue. After you call this function, you can run the event queue using processEventQueue() or empty it using clearEventQueue().

Parameters

This function accepts the same parameters as the event() function. It supports both standard and custom events.

Here's an example of how to use the addToEventQueue() function to save events to the event queue.

In this scenario, we add different events to the event queue depending on whether a user clicked a dropdown and a dropdown item.

In the following order, either the DROPDOWN_CLICK then the DROPDOWN_ITEM_CLICK events are added to the event queue, or the DROPDOWN_CLICK then the DROPDOWN_ABANDON events are added.

if (clickedDropdown) {
  engage.addToEventQueue("DROPDOWN_CLICK", eventData);

  if (clickedDropdownItem) {
    engage.addToEventQueue("DROPDOWN_ITEM_CLICK", eventData);
  } else {
    engage.addToEventQueue("DROPDOWN_ABANDON", eventData);
  };

  engage.processEventQueue();
};
if (clickedDropdown) {
  engage.addToEventQueue("DROPDOWN_CLICK", eventData);

  if (clickedDropdownItem) {
    engage.addToEventQueue("DROPDOWN_ITEM_CLICK", eventData);
  } else {
    engage.addToEventQueue("DROPDOWN_ABANDON", eventData);
  };

  engage.processEventQueue();
};

Engage.processEventQueue()

The processEventQueue() function:

  • Runs the event queue, sending all the events that are in it.

  • Sends the events in the order they were added to the event queue.

  • Waits for a response from each event before it sends the next event.

Parameters

none

Here's an example of how to use the processEventQueue() function to run the event queue.

In this scenario, we add different events to the event queue depending on whether a user clicked a dropdown and a dropdown item.

When you run the event queue, either the DROPDOWN_CLICK then the DROPDOWN_ITEM_CLICK events are sent, or the DROPDOWN_CLICK then the DROPDOWN_ABANDON events.

if (clickedDropdown) {
  engage.addToEventQueue("DROPDOWN_CLICK", eventData);

  if (clickedDropdownItem) {
    engage.addToEventQueue("DROPDOWN_ITEM_CLICK", eventData);
  } else {
    engage.addToEventQueue("DROPDOWN_ABANDON", eventData);
  };

  engage.processEventQueue();
};
if (clickedDropdown) {
  engage.addToEventQueue("DROPDOWN_CLICK", eventData);

  if (clickedDropdownItem) {
    engage.addToEventQueue("DROPDOWN_ITEM_CLICK", eventData);
  } else {
    engage.addToEventQueue("DROPDOWN_ABANDON", eventData);
  };

  engage.processEventQueue();
};

Engage.clearEventQueue()

The clearEventQueue() function empties the event queue, removing all the events that are in it, without sending any of the events.

Parameters

none

Here's an example of how to use the clearEventQueue() function to empty the event queue.

In this scenario, we add different events to the event queue depending on whether a user clicked a dropdown and a dropdown item.

If a certain condition is met, we decide to empty the event queue and not send any of the events we previously added to it.

if (clickedDropdown) {
  engage.addToEventQueue("DROPDOWN_CLICK", eventData);

  if (clickedDropdownItem) {
    engage.addToEventQueue("DROPDOWN_ITEM_CLICK", eventData);
  } else {
    engage.addToEventQueue("DROPDOWN_ABANDON", eventData);
  };

  if (timeout) {
    engage.clearEventQueue();
  };
};
if (clickedDropdown) {
  engage.addToEventQueue("DROPDOWN_CLICK", eventData);

  if (clickedDropdownItem) {
    engage.addToEventQueue("DROPDOWN_ITEM_CLICK", eventData);
  } else {
    engage.addToEventQueue("DROPDOWN_ABANDON", eventData);
  };

  if (timeout) {
    engage.clearEventQueue();
  };
};

Engage.personalize(personalizationData[, timeout])

The personalize() function runs an interactive full stack experience or an interactive full stack experiment that's 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.

Web experiences and web experiments are run by the Engage SDK 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

personalizationData

object

Event and experiment data.

Specify the friendlyId in this object.

[timeout]

optional

integer

Minimum 0

The number of milliseconds before the function times out and returns an error.

When you use the timeout parameter, you should use try-catch blocks to handle errors.

For example, set the value to 10000 for the function to time out in 10 seconds.

Here's an example of how to run an experience or experiment and log it to the console.

import { engage } from "./engage.js";
// ...

const handlePersonalization = async () => {
    const response = await engage.personalize(personalizationData);
    console.log(response);
};
import { engage } from "./engage.js";
// ...

const handlePersonalization = async () => {
    const response = await engage.personalize(personalizationData);
    console.log(response);
};

EngageServer.pageView(eventData, req[, extensionData])

Note

This is a server-side function used for implementing server-side tracking. If you want to implement client-side tracking instead, use the client-side functions.

The pageView() function sends a VIEW event. The VIEW event triggers every time your webpage loads. You should send a VIEW event from every webpage that you want to track on your website.

Parameters

Parameter

Type

Description

eventData

object

All the event data.

req

object

The HTTP request.

[extensionData]

optional

object

Maximum 50 custom attributes of your choice.

Example 13. Next app

Here's an example of how to use the pageView() function in a Next app.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send VIEW events
  const eventData = {
    channel: "WEB",
    currency: "EUR"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.pageView(eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send VIEW events
  const eventData = {
    channel: "WEB",
    currency: "EUR"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.pageView(eventData, req, extensionData);
  return res;
};

EngageServer.identity(eventData, req[, extensionData])

Note

This is a server-side function used for implementing server-side tracking. If you want to implement client-side tracking instead, use the client-side functions.

The identity() function sends an IDENTITY event. The IDENTITY event is used to resolve the identity of an anonymous user of your app and turn them into a known user.

Parameters

Parameter

Type

Description

eventData

object

All the event data.

req

object

The HTTP request.

[extensionData]

optional

object

Maximum 50 custom attributes of your choice.

Example 14. Next app

Here's an example of how to use the identity() function in a Next app.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send IDENTITY event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    identifiers: [
        {
            id: "123456",
            provider: "BXLP"
        }
    ]
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.identity(eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send IDENTITY event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    identifiers: [
        {
            id: "123456",
            provider: "BXLP"
        }
    ]
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.identity(eventData, req, extensionData);
  return res;
};

EngageServer.event(type, eventData, req[, extensionData])

Note

This is a server-side function used for implementing server-side tracking. If you want to implement client-side tracking instead, use the client-side functions.

The event() function sends one of the following:

Parameters for a standard event

Parameter

Type

Description

type

string

The type of the standard event. If you set this value to any of the Sitecore Personalize reserved event names, for example, VIEW, ADD, or CONFIRM, the event becomes a standard event.

Sitecore Personalize reserved event names:

eventData

object

All the event data specific to the standard event type, for example, an ADD event.

req

object

The HTTP request.

[extensionData]

optional

object

Maximum 50 custom attributes of your choice.

Parameters for a custom event

Parameter

Type

Description

type

string

The name of the custom event. If you set this value to a custom value of your choice different than Sitecore Personalize reserved event names, for example, CUSTOM_EVENT_SEARCH or myretailsite:CLICKED_POPUP, the event becomes a custom event.

eventData

object

The required attributes that every event object must include, and optional attributes that event objects can include.

req

object

The HTTP request.

[extensionData]

optional

object

Maximum 50 custom attributes of your choice.

Example 15. ORDER_CHECKOUT event

Here's an example of how to use the event() function to send an ORDER_CHECKOUT event. The eventData object must contain all the required attributes for the event type, in this example, for an ORDER_CHECKOUT event.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send ORDER_CHECKOUT event
  const eventData = {
  channel: "WEB",
  currency: "EUR",
  pointOfSale: "myretailsite/ireland",
  language: "EN",
  page: "checkout page",
  order: {
    referenceId: "123456",
    orderedAt: "2023-08-23T16:17:16.000Z",
    status: "PURCHASED",
    currencyCode: "EUR",
    price: 200,
    paymentType: "Card",
    cardType: "Visa",
    extensions: [ 
       {
          name: "ext",
          key: "default",
          refundable: true
       }
    ],
    orderItems: [
       {
          type: "MOBILE_PHONE",
          referenceId: "REF-123",
          orderedAt: "2023-08-23T16:17:16.000Z",
          status: "PURCHASED",
          currencyCode: "EUR",
          price: 200,
          name: "Mobile phone of type x",
          productId: "MOBILE_PHONE_TYPE_X",
          quantity: 1,
          extensions: [
             {
                name: "ext",
                key: "default",
                phoneColor: "Gold",
                insurance: false
             }
          ]
       }
    ]
 }
};

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("ORDER_CHECKOUT", eventData, req, extensionData);
  return res;
};
Example 16. ADD event

Here's an example of how to use the event() function to send an ADD event. The eventData object must contain all the required attributes for the event type, in this example, for an ADD event.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send ADD event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "products",
    product: {
        name: "GHT 84 Lace Sneaker",
        type: "FOOTWEAR",
        item_id: "SHOES_8475GHT",
        productId: "example_product_id",
        referenceId: "MA-490094",
        orderedAt: new Date().toISOString(),
        quantity: 1,
        price: 7.99,
        currency: "EUR",
        originalPrice: 7.79,
        originalCurrencyCode: "USD"
    }
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("ADD", eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send ADD event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "products",
    product: {
        name: "GHT 84 Lace Sneaker",
        type: "FOOTWEAR",
        item_id: "SHOES_8475GHT",
        productId: "example_product_id",
        referenceId: "MA-490094",
        orderedAt: new Date().toISOString(),
        quantity: 1,
        price: 7.99,
        currency: "EUR",
        originalPrice: 7.79,
        originalCurrencyCode: "USD"
    }
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("ADD", eventData, req, extensionData);
  return res;
};
Example 17. CONFIRM event

Here's an example of how to use the event() function to send a CONFIRM event. The eventData object must contain all the required attributes for the event type, in this example, for a CONFIRM event.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send CONFIRM event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "checkout",
    product: [
      { item_id: "SHOES_8475GHT" }
    ]
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("CONFIRM", eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send CONFIRM event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "checkout",
    product: [
      { item_id: "SHOES_8475GHT" }
    ]
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("CONFIRM", eventData, req, extensionData);
  return res;
};
Example 18. CHECKOUT event

Here's an example of how to use the event() function to send a CHECKOUT event. The eventData object must contain all the required attributes for the event type, in this example, for a CHECKOUT event.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send CHECKOUT event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "home",
    reference_id: "MA-490094",
    status: "PURCHASED"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("CHECKOUT", eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send CHECKOUT event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "home",
    reference_id: "MA-490094",
    status: "PURCHASED"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("CHECKOUT", eventData, req, extensionData);
  return res;
};
Example 19. PAYMENT event

Here's an example of how to use the event() function to send a PAYMENT event. The eventData object must contain all the required attributes for the event type, in this example, for a PAYMENT event.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send PAYMENT event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "home",
    paymentType: "voucher"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("PAYMENT", eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send PAYMENT event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "home",
    paymentType: "voucher"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("PAYMENT", eventData, req, extensionData);
  return res;
};
Example 20. CLEAR_CART event

Here's an example of how to use the event() function to send a CLEAR_CART event. The eventData object must contain all the required attributes for the event type, in this example, for a CLEAR_CART event.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send CLEAR_CART event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "home"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("CLEAR_CART", eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send CLEAR_CART event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "home"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("CLEAR_CART", eventData, req, extensionData);
  return res;
};
Example 21. SEARCH event

Here's an example of how to use the event() function to send a SEARCH event. The eventData object must contain all the required attributes for the event type, in this example, for a SEARCH event.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send SEARCH event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "search result page",
    "product_name": "airSupport",
    "product_type": "RUNNERS"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("SEARCH", eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send SEARCH event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "search result page",
    "product_name": "airSupport",
    "product_type": "RUNNERS"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("SEARCH", eventData, req, extensionData);
  return res;
};
Example 22. Custom event

Here's an example of how to use the event() function to send a custom event called myretailsite:CLICKED_POPUP. eventData contains all the required attributes for the event data object. extensionData contains the custom data.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send custom event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "search result page"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("myretailsite:CLICKED_POPUP", eventData, req, extensionData);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  const engageServer = await initServer(engageSettings);

  // Send custom event
  const eventData = {
    channel: "WEB",
    currency: "EUR",
    language: "EN",
    page: "search result page"
  };

  const extensionData = {
    customKey: "customValue"
  };

  await engageServer.event("myretailsite:CLICKED_POPUP", eventData, req, extensionData);
  return res;
};

EngageServer.personalize(personalizationData, callback[, timeout])

Note

This is a server-side function used for implementing server-side tracking. If you want to implement client-side tracking instead, use the client-side functions.

The personalize() function runs an interactive full stack experience or an interactive full stack experiment that's 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.

Web experiences and web experiments are run by the Engage SDK 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

personalizationData

object

Event and experiment data.

Specify the friendlyId in this object.

callback

function

This callback function handles the response.

N/A

[timeout]

optional

integer

Minimum 0

The number of milliseconds before the function times out and returns an error.

When you use the timeout parameter, you should use try-catch blocks to handle errors.

For example, set the value to 200 for the function to time out in 0.2 seconds.

Here's an example of how to run an experience or experiment and log it to the console.

export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  // Personalization data
  const personalizationData = {
    channel: "WEB",
    currency: "EUR",
    friendlyId: "running_shoes_popup_02",
    // optional attributes:
    params: { key: "value" }
}

  const engageServer = await initServer(engageSettings);

  await engageServer.personalize(personalizationData, (res) => {console.log(res)}, 4000);
  return res;
};
export async function middleware(req) {
  const res = NextResponse.next();

  // Load Engage API
  const engageSettings = {
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>"
  };

  // Personalization data
  const personalizationData = {
    channel: "WEB",
    currency: "EUR",
    friendlyId: "running_shoes_popup_02",
    // optional attributes:
    params: { key: "value" }
}

  const engageServer = await initServer(engageSettings);

  await engageServer.personalize(personalizationData, (res) => {console.log(res)}, 4000);
  return res;
};

window.Engage.triggerExperiences()

The triggerExperiences() function reruns every web experience and web experiment that's live in Sitecore Personalize. This function is particularly useful if you want to run personalization, for example:

  • In a multi-page application, on the same page in response to user input.

  • In a single-page application (SPA), when the user navigates between routes.

You can only use this function if you previously set the webPersonalization attribute to true in the settings object in the Engage.init() function, on the client side of your app.

Here's an example of how to use the triggerExperiences() function to make sure that web experiences and web experiments always run on the /contact route of a SPA app.

import { init } from "@sitecore/engage";

let engage;

const loadEngage = async () => {
  engage = await init({
    // ...
    webPersonalization: true
  });

  // Make sure web experiences and web experiments always run in SPA apps:
  if (window.location.pathname.includes("/contact")) {
    window.Engage.triggerExperiences();
  }
};
import { init } from "@sitecore/engage";

let engage;

const loadEngage = async () => {
  engage = await init({
    // ...
    webPersonalization: true
  });

  // Make sure web experiences and web experiments always run in SPA apps:
  if (window.location.pathname.includes("/contact")) {
    window.Engage.triggerExperiences();
  }
};

Event data object

Use the event data object to collect behavioral and transactional data about a user's interaction with your app. You can optionally collect custom data using the extension data object. After you create your event data objects, you can send the events to Sitecore Personalize.

Required attributes

At a minimum, every event data object must include the following attributes. Note that event data objects for different event types may require more attributes than listed in this table.

Attribute

Type

Description

Example

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

For example, for webpages, the channel is WEB. For mobile app screens, the channel is MOBILE_APP.

Must be one of:

  • AIRPORT_KIOSK

  • BRANCH

  • CALL_CENTER

  • EMAIL

  • GDS

  • KIOSK

  • MOBILE_APP

  • MOBILE_WEB

  • SMS

  • OFFLINE

  • OTA

  • OTHER

  • WEB

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

For example, if the user selects Australian dollars as the currency on your website, the currency is AUD.

  • EUR

  • GBP

  • USD

pointOfSale

string

The name of the point of sale where the interaction with your brand takes place.

You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize.

If you did not specify pointOfSale in the settings object, you must specify it in every event data object.

If you specified pointOfSale in the settings object, it's optional in event data objects. You can specify it in any event data object to override the original value of pointOfSale, previously specified in the settings object, for that specific event.

myretailsite/ireland

Optional attributes

An event data object can optionally include the following attributes:

Attribute

Type

Description

Example

language

string (uppercase ISO 639-1)

The language the user is using your app in.

For example, if the user selects the Japanese language on your website, the language is JA.

The default is EN.

  • DE

  • EN

  • FR

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

The default is Home Page.

  • home

  • contact-us.html

VIEW event

The event data object for a VIEW event must include all the required attributes for event data objects. No further attributes are required. The object can optionally include the following attributes:

Attribute

Type

Description

Example

pageVariantId

string

The ID of a personalized page variant.

page_variant_3

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.pageView() function.

Example 23. VIEW event

Here's an example of the event data object for a VIEW event.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    pageVariantId: "351"
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    pageVariantId: "351"
}
Example 24. VIEW event with UTM parameters

Here's an example of an event data object for a VIEW event that is sent to Sitecore Personalize with UTM parameters included. By default, the VIEW event data object includes UTM parameters. You can exclude UTM parameters from the VIEW event data object by setting the value for includeUTMParameters to false in the settings object.

When a VIEW event triggers, the event data includes all the UTM parameters that are in the URL:

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

IDENTITY event

The event data object for an IDENTITY event must include all the required attributes for event data objects plus the following attributes:

Attribute

Type

Description

Example

identifiers

array of objects

The identity identifiers that are used to identify the users of your app.

identifiers: [{
    "id": "123456",
    "provider": "BXLP"
}]

The identifiers array of objects:

Attribute

Type

Description

Example

Required/optional

id

string

The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.

123456

Required

provider

string

The name of your organization's identity system, external to Sitecore Personalize, that provided the unique guest identifier.

BXLP

Required

expiryDate

string (ISO 8601)

The date the unique guest identifier expires. This is determined by your organization's identity system.

2023-04-15T08:39:44.868Z

Optional

The object can optionally include personally identifiable information (PII):

Attribute

Type

Description

Example

email

string (lowercase recommended)

The email address of the guest.

jane.doe@myretailsite.com

title

string (title case)

The title of the guest.

  • Miss

  • Mr

  • Mrs

  • Ms

firstName

string (title case recommended)

The first name of the guest.

Jane

lastName

string (title case recommended)

The last name of the guest.

Doe

gender

string

The gender of the guest.

female

dob

string (ISO 8601)

The date of birth of the guest.

1983-04-15T08:39:44.868Z

mobile

string

The mobile number of the guest.

+3531234567

phone

string

The phone number of the guest.

+3531234567

street

array of strings (title case recommended)

The street address of the guest.

["Tara Street"]

city

string (title case recommended)

The city address of the guest.

Dublin

state

string (title case recommended)

The state address of the guest.

Oregon

country

string (uppercase ISO 3166-1 alpha-2)

The country address of the guest.

IE

postalCode

string

The postal code of the guest.

D2

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.identity() function.

Here's an example of the event data object for an IDENTITY event. This event data object contains the identifiers array of objects and the following, optional PII attributes: email, firstName, lastName.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    email: "jane.doe@myretailsite.com",
    firstName: "Jane",
    lastName: "Doe",
    identifiers: [
        {
            id: "123456",
            provider: "BXLP"
        }
    ]
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    email: "jane.doe@myretailsite.com",
    firstName: "Jane",
    lastName: "Doe",
    identifiers: [
        {
            id: "123456",
            provider: "BXLP"
        }
    ]
}

ORDER_CHECKOUT event

const eventData = {
  channel: "WEB",
  currency: "EUR",
  pointOfSale: "myretailsite/ireland",
  language: "EN",
  page: "checkout page",
  order: {
    referenceId: "123456",
    orderedAt: "2023-08-23T16:17:16.000Z",
    status: "PURCHASED",
    currencyCode: "EUR",
    price: 200,
    paymentType: "Card",
    cardType: "Visa",
    extensions: [
      {
        name: "ext",
        key: "default",
        refundable: true,
      },
    ],
    orderItems: [
      {
        type: "MOBILE_PHONE",
        referenceId: "REF-123",
        orderedAt: "2023-08-23T16:17:16.000Z",
        status: "PURCHASED",
        currencyCode: "EUR",
        price: 200,
        name: "Mobile phone of type x",
        productId: "MOBILE_PHONE_TYPE_X",
        quantity: 1,
        extensions: [
          {
            name: "ext",
            key: "default",
            phoneColor: "Gold",
            insurance: false,
          },
        ],
      },
    ],
  },
}

ADD event

The event data object for an ADD event must include all the required attributes for event data objects plus the following attribute:

Attribute

Type

Description

Example

product

object

Data about the product that the user adds to the cart.

N/A

The product object:

Attribute

Type

Description

Example

Required/optional

name

string (title case recommended)

The name of the product that the user added to the cart.

GHT 84 Lace Sneaker

Required

type

string (uppercase)

The type of product that the user added to the cart.

FOOTWEAR

Required

item_id

string

The item ID of the product that the user added to the cart.

Used in Extract, Transform, Load (ETL) data integration to create the order.

You must pass this string into an object in the product array of the CONFIRM event for the order to be successfully created.

SHOES_8475GHT

Required

productId

string

The ID of the product that the user added to the cart.

Used in Analytics for reporting.

example_product_id

Required

referenceId

string

An ID generated by your organization to reference the order item.

FOOTWEAR-001-01

Required

orderedAt

string (ISO 8601)

Format: YYYY-MM-DD’T’hh:mm:ss.<timezone>

The date and time the user added the product to the cart.

2023-04-15T12:42:16.001Z

Required

quantity

integer

The number of units of the product that the user added to the cart.

Total price = quantity × price

1

Required

price

float

The unit price of the product.

Total price = quantity × price

7.99

Required

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency that the product price is specified in.

  • EUR

  • GBP

  • USD

Required

originalPrice

float

The unit price of the order item before conversion to the organization's currency.

7.99

Optional

originalCurrencyCode

The original currency code for the order item.

  • EUR

  • GBP

  • USD

Optional

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.event() function.

Here's an example of the event data object for an ADD event.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "products",
    product: {
        name: "GHT 84 Lace Sneaker",
        type: "FOOTWEAR",
        item_id: "SHOES_8475GHT",
        productId: "example_product_id",
        referenceId: "MA-490094",
        orderedAt: new Date().toISOString(),
        quantity: 1,
        price: 7.99,
        currency: "EUR",
        originalPrice: 7.79,
        originalCurrencyCode: "USD"
    }
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "products",
    product: {
        name: "GHT 84 Lace Sneaker",
        type: "FOOTWEAR",
        item_id: "SHOES_8475GHT",
        productId: "example_product_id",
        referenceId: "MA-490094",
        orderedAt: new Date().toISOString(),
        quantity: 1,
        price: 7.99,
        currency: "EUR",
        originalPrice: 7.79,
        originalCurrencyCode: "USD"
    }
}
Example 25. Product item IDs in ADD and in CONFIRM events

Here's an example of how multiple product item IDs are linked in ADD and in CONFIRM event data objects.

For each item ID included in an object in the product array of the CONFIRM event data object, there must be a preceding ADD event data object where the product item ID is specified in product.item_id.

// ADD event data object for "SHOES_8475GHT"
const addEventData = {
    // ...
    product: {
        // ...
        item_id: "SHOES_8475GHT"
    }
}

// ADD event data object for "JEANS_W33L31"
const addEventData = {
    // ...
    product: {
        // ...
        item_id: "JEANS_W33L31"
    }
}

// CONFIRM event data object listing all product item IDs
const confirmEventData = {
    // ...
    product: [
        { item_id: "SHOES_8475GHT" },
        { item_id: "JEANS_W33L31" }
    ]
}
// ADD event data object for "SHOES_8475GHT"
const addEventData = {
    // ...
    product: {
        // ...
        item_id: "SHOES_8475GHT"
    }
}

// ADD event data object for "JEANS_W33L31"
const addEventData = {
    // ...
    product: {
        // ...
        item_id: "JEANS_W33L31"
    }
}

// CONFIRM event data object listing all product item IDs
const confirmEventData = {
    // ...
    product: [
        { item_id: "SHOES_8475GHT" },
        { item_id: "JEANS_W33L31" }
    ]
}

CONFIRM event

The event data object for a CONFIRM event must include all the required attributes for event data objects plus the following attributes:

Attribute

Type

Description

Example

product

array of objects

A list of objects, where each object contains the item ID of the product that the user added to the cart.

Use the item ID from product.item_id in the event data object for the ADD event.

product: [
 { item_id: "SHOES_8475GHT" },
 { item_id: "TSHIRT_XLGRN" }
]

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.event() function.

Here's an example of the event data object for a CONFIRM event.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "checkout",
    product: [
      { item_id: "SHOES_8475GHT" }
    ]
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "checkout",
    product: [
      { item_id: "SHOES_8475GHT" }
    ]
}
Example 26. Product item IDs in ADD and in CONFIRM events

Here's an example of how multiple product item IDs are linked in ADD and in CONFIRM event data objects.

For each item ID included in an object in the product array of the CONFIRM event data object, there must be a preceding ADD event data object where the product item ID is specified in product.item_id.

// ADD event data object for "SHOES_8475GHT"
const addEventData = {
    // ...
    product: {
        // ...
        item_id: "SHOES_8475GHT"
    }
}

// ADD event data object for "JEANS_W33L31"
const addEventData = {
    // ...
    product: {
        // ...
        item_id: "JEANS_W33L31"
    }
}

// CONFIRM event data object listing all product item IDs
const confirmEventData = {
    // ...
    product: [
        { item_id: "SHOES_8475GHT" },
        { item_id: "JEANS_W33L31" }
    ]
}
// ADD event data object for "SHOES_8475GHT"
const addEventData = {
    // ...
    product: {
        // ...
        item_id: "SHOES_8475GHT"
    }
}

// ADD event data object for "JEANS_W33L31"
const addEventData = {
    // ...
    product: {
        // ...
        item_id: "JEANS_W33L31"
    }
}

// CONFIRM event data object listing all product item IDs
const confirmEventData = {
    // ...
    product: [
        { item_id: "SHOES_8475GHT" },
        { item_id: "JEANS_W33L31" }
    ]
}

CHECKOUT event

The event data object for a CHECKOUT event must include all the required attributes for event data objects plus the following attributes:

Attribute

Type

Description

Example

reference_id

string (uppercase)

The order ID.

MA-490094

status

string (uppercase)

The order status.

Must be one of:

  • PURCHASED

  • PAYMENT_PENDING

  • CONFIRMED

  • CANCELLED

  • REFUNDED

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.event() function.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    reference_id: "MA-490094",
    status: "PURCHASED"
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    reference_id: "MA-490094",
    status: "PURCHASED"
}

PAYMENT event

The event data object for a PAYMENT event must include all the required attributes for event data objects plus the following attribute:

Attribute

Type

Description

Example

paymentType

string

The payment method associated with a checkout.

  • card

  • PayPal

  • voucher

  • other

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.event() function.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    paymentType: "voucher"
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home",
    paymentType: "voucher"
}

CLEAR_CART event

The event data object for a CLEAR_CART event must include all the required attributes for event data objects. No further attributes are required.

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.event() function.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home"
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home"
}

SEARCH event

The event data object for a SEARCH event must include all the required attributes for event data objects plus the following attributes:

Attribute

Type

Description

Example

product_name

string

The product name the guest searched for.

airSupport

product_type

string (uppercase)

The product type the guest searched for.

RUNNERS

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.event() function.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "search result page",
    "product_name": "airSupport",
    "product_type": "RUNNERS"
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "search result page",
    "product_name": "airSupport",
    "product_type": "RUNNERS"
}

Custom event

The event data object for a custom event must include all the required attributes for event data objects. No further attributes are required.

You can also add custom attributes of your choice.

After you create this event data object, you can optionally extend this event using the extension data object. Then, you can send the event using the Engage.event() function.

const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home"
}
const eventData = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    language: "EN",
    page: "home"
}

Extension data object

Use the extension data object to collect custom data that you then send with an event to Sitecore Personalize. This is an optional object that you can specify as the last function argument when you send events. This object accepts a maximum of 50 custom attributes of your choice.

After you send the event, the data in this object becomes available for personalization and decisioning.

When you build this object, use a flat object structure. Sitecore Personalize automatically flattens nested objects and renames the keys as necessary. For example:

Here's an example of how to use the event() function to send a custom event called myretailsite:CLICKED_POPUP. eventData contains all the required attributes for the event data object. extensionData contains the custom data.

import { engage } from "./engage.js";
// ...

const handleClick = async (e) => {
    e.preventDefault();

    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("myretailsite:CLICKED_POPUP", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...

const handleClick = async (e) => {
    e.preventDefault();

    const eventData = {
      channel: "WEB",
      currency: "EUR",
      pointOfSale: "myretailsite/ireland",
      language: "EN",
      page: "home"
    };

    const extensionData = {
      customKey: "customValue"
    };

    await engage.event("myretailsite:CLICKED_POPUP", eventData, extensionData);
};

Personalization data object

Use the personalization data object to collect identifying data about a user, and the friendlyID of an interactive full stack experience or an interactive full stack experiment that you want to run for the user. You then send the object to Sitecore Personalize, and Sitecore Personalize runs the experience or experiment.

After you create this object, you can send it using the Engage.personalize() function.

Required attributes

At a minimum, every personalization data object must include the following attributes:

Attribute

Type

Description

Example

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

For example, for webpages, the channel is WEB. For mobile app screens, the channel is MOBILE_APP.

Must be one of:

  • AIRPORT_KIOSK

  • BRANCH

  • CALL_CENTER

  • EMAIL

  • GDS

  • KIOSK

  • MOBILE_APP

  • MOBILE_WEB

  • SMS

  • OFFLINE

  • OTA

  • OTHER

  • WEB

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

For example, if the user selects Australian dollars as the currency on your website, the currency is AUD.

  • EUR

  • GBP

  • USD

pointOfSale

string

The name of the point of sale where the interaction with your brand takes place.

You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize.

If you did not specify pointOfSale in the settings object, you must specify it in the personalization data object.

If you specified pointOfSale in the settings object, it's optional in the personalization data object. You can specify it in the personalization data object to override the original value of pointOfSale, previously specified in the settings object, for that specific personalization.

myretailsite/ireland

friendlyId

string

The ID of a live interactive full stack experience or live interactive full stack experiment that you want to run.

running_shoes_popup_02

Optional attributes

A personalization data object can optionally include the following attributes:

Attribute

Type

Description

Example

language

string (uppercase ISO 639-1)

The language the user is using your app in.

For example, if the user selects the Japanese language on your website, the language is JA.

The default is EN.

  • DE

  • EN

  • FR

params

object

An object of your choice.

Use a flat object structure. Sitecore Personalize automatically flattens nested objects and renames the keys as necessary. For example:

params: { key: "value" }

Optional guest identifier attributes

A personalization data object can optionally include no more than one of the following guest identifier attributes. If the personalization data object doesn't contain any of these attributes, the browser ID becomes the guest identifier.

Attribute

Type

Description

Example

email

string (lowercase recommended)

The email address of the guest.

jane.doe@myretailsite.com

identifier

object

The identity identifiers that are used to identify the users of your app.

identifier: {
    "id": "123456",
    "provider": "BXLP"
}

The identifier object:

Attribute

Type

Description

Example

Required/optional

id

string

The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.

123456

Required

provider

string

The name of your organization's identity system, external to Sitecore Personalize, that provided the unique guest identifier.

BXLP

Required

Example 27. Personalization data object with browser ID

Here's an example of a personalization data object that doesn't contain the email attribute or the identifier attribute to identify the guest. In this case, the browser ID is the guest identifier. This personalization data object also contains an optional custom object.

const personalization = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    friendlyId: "running_shoes_popup_02",
    // optional attributes:
    params: { key: "value" }
}
const personalization = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    friendlyId: "running_shoes_popup_02",
    // optional attributes:
    params: { key: "value" }
}
Example 28. Personalization data object with email

Here's an example of a personalization data object that uses the email attribute as the guest identifier.

const personalization = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    friendlyId: "running_shoes_popup_02",
    // guest identifier:
    email: "jane.doe@myretailsite.com"
}
const personalization = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    friendlyId: "running_shoes_popup_02",
    // guest identifier:
    email: "jane.doe@myretailsite.com"
}
Example 29. Personalization data object with identifiers

Here's an example of a personalization data object that uses the identifiers attribute as the guest identifier.

const personalization = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    friendlyId: "running_shoes_popup_02",
    // guest identifier:
    identifier: {
        id: "123456",
        provider: "BXLP"
    }
}
const personalization = {
    channel: "WEB",
    currency: "EUR",
    pointOfSale: "myretailsite/ireland",
    friendlyId: "running_shoes_popup_02",
    // guest identifier:
    identifier: {
        id: "123456",
        provider: "BXLP"
    }
}

Settings object

Use the settings object to initialize the Engage JavaScript Library or the Engage SDK. In the settings object, you include details about your Sitecore Personalize instance.

The Engage SDK supports setting cookies from the client and from the server.

  • To set cookies from the client, you must set the forceServerCookieMode attribute to false and pass the settings object to the Engage.init() function.

  • To set cookies from the server, you must set the forceServerCookieMode attribute to true and pass the settings object to the Engage.init() function on the client side, and to the Engage.initServer() function on the server side.

The settings object includes the following attributes:

Attribute

Type

Description

Example

Required/optional

clientKey

string

Your client key.

ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe

Required

targetURL

string

Your Stream API target endpoint.

The value depends on the location of your Sitecore Personalize server.

Must be one of:

  • https://api-engage-eu.sitecorecloud.io

  • https://api-engage-ap.sitecorecloud.io​

  • https://api-engage-us.sitecorecloud.io

Required

includeUTMParameters

boolean

Specify whether to add every UTM parameter from the URL of the current webpage to the event object.

The default is true.

If true, UTM parameters are added to the VIEW event object.

true or false

Optional

cookieDomain

string

Your cookie domain.

The default is what the browser sets.

  • .myretailsite.com

  • .beta.myretailsite.com

  • localhost

Optional

cookieExpiryDays

integer

The number of days before the cookie expires.

If you don't specify this value, the cookie expires according to the Max-Age that the browser sets.

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

Optional

cookiePath

string

A URL path that must exist in the requested URL in order to send the cookie.

N/A

Optional

forceServerCookieMode

boolean

Specify whether to set cookies from the client or from the server.

If you can access the server side of your app, you can choose to set cookies from the server instead of the client.

To set cookies from the server, set the value to true on both the server and the client side.

The default is false.

true or false

Optional

webPersonalization

boolean or object

On the client side, specify whether you want to run personalization with Sitecore Personalize. This attribute is not available on the server side.

If you don't specify this attribute on the client side, or if you specify it and set the value to false, personalization will not be available.

If you set the value to true or to an object, you must also specify the pointOfSale.

If you set the value to true, a web personalization script will load in your app with async but without defer.

To customize the loading of the script, set the value to an object. In the object, customize async and defer using asyncScriptLoading and deferScriptLoading, respectively. For these attributes, set the values to boolean values.

If you received a custom URL from Sitecore to load the web personalization script, specify the URL as a string in the object using baseURLOverride.

The default is false.

  • false

  • true

  • { asyncScriptLoading: false }

  • { asyncScriptLoading: false, deferScriptLoading: true }

  • If you have a custom URL to load the web personalization script:

    { baseURLOverride: "https://..." }

Optional on the client side.

Not available on the server side.

pointOfSale

string

The name of the point of sale where the interaction with your brand takes place.

If you specified the webPersonalization attribute on the client side and set the value to true or to an object, you must specify pointOfSale.

You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize.

If you don't specify pointOfSale in the settings object, you must specify it in every event data object and in the personalization data object.

myretailsite/ireland

Required if you specified the webPersonalization attribute. Optional otherwise.

Initialize the Engage SDK, setting cookies from the client and using web personalization:

import { init } from "@sitecore/engage";

const engageSettings = {
  clientKey: "<client_key_PLACEHOLDER>",
  targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
  pointOfSale: "<point_of_sale_PLACEHOLDER>",
  cookieDomain: "<cookie_domain_PLACEHOLDER>",
  cookieExpiryDays: 365,
  forceServerCookieMode: false,
  webPersonalization: "<boolean_or_object>"
};

const loadEngage = async () => {
  // Load Engage API
  const engage = await init(engageSettings);
};
import { init } from "@sitecore/engage";

const engageSettings = {
  clientKey: "<client_key_PLACEHOLDER>",
  targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
  pointOfSale: "<point_of_sale_PLACEHOLDER>",
  cookieDomain: "<cookie_domain_PLACEHOLDER>",
  cookieExpiryDays: 365,
  forceServerCookieMode: false,
  webPersonalization: "<boolean_or_object>"
};

const loadEngage = async () => {
  // Load Engage API
  const engage = await init(engageSettings);
};

Troubleshooting

This topic describes the most common errors and solutions when integrating using the Engage JavaScript Library or the Engage SDK.

Errors in the console

400 Bad Request when running Engage.personalize()

This error occurs when you're trying to return an experiment or experience for a user of your app using an email address or other identifiers that don't exist in Sitecore Personalize. To fix the error, in the personalization data object, specify identifiers that exist in Sitecore Personalize.

401 Unauthorized

This error occurs when the value for the clientKey attribute is incorrect. To fix the error, set the value to the correct client key.

404 Not Found

This error occurs in the following cases:

  • The browser ID was not stored as a cookie in the web browser. This happens when, for example, a user of your app rejects cookies or the web browser is blocking cookies. To send events and call personalization, the browser ID must be stored as a cookie in the web browser.

  • The value for the targetURL attribute is the wrong URL from the available URLs for the Stream API. To fix the error, set the value to the correct Stream API target endpoint.

Cookie has been rejected for invalid domain

This error occurs when the value for the cookieDomain is incorrect. To fix the error, set the value to the correct cookie domain.

Cross-origin request blocked

This error occurs when the value for the targetURL attribute is different than the available URLs for the Stream API. To fix the error, set the value to the correct Stream API target endpoint.

IE errors

IE errors are related to initializing the Engage SDK.

Code

Description

Note

IE-0001

The window object is not available on the server side. Use the window object only on the client side, and in the correct execution context.

This error can occur when you call Engage functions on the server.

Make sure to call Engage functions where the window object is present.

IE-0002

Cannot retrieve the cookie from the server.

See a code sample for setting cookies from the server.

IE-0003

Timeout exceeded. The server did not respond within the allotted time.

This error occurs when you call a function with the timeout parameter, then the function makes a network request to the server, but the server doesn't respond in time.

When you use the timeout parameter, you should use try-catch blocks to handle errors.

IV errors

IV errors are related to incorrect values and wrongly formatted objects in the event data.

Code

Description

Note

IV-0001

Incorrect value for targetURL. Set the value to a valid URL string.

Set the value to the correct Stream API target endpoint.

IV-0002

Incorrect value for dob.

Format the value according to ISO 8601.

See examples of correctly formatted data.

IV-0003

Incorrect value for email. Set the value to a valid email address.

IV-0004

Incorrect value for expiryDate.

Format the value according to ISO 8601.

IV-0005

This event supports maximum {{max}} attributes. Reduce the number of attributes.

IV-0006

Incorrect value for the timeout parameter. Set the value to an integer greater than or equal to 0.

N/A

MV errors

MV errors are related to missing values in the event data.

Code

Description

Note

MV-0001

clientKey is required.

Set the value to your client key.

MV-0002

targetURL is required.

Set the value to the correct Stream API target endpoint.

MV-0003

pointOfSale is required.

Set the value to the name of your point of sale.

MV-0004

identifiers is required.

See examples of correctly formatted data.

MV-0008

friendlyId is required.

See examples of correctly formatted data.

MV-0009

pointOfSale cannot be empty.

Set the value to the name of your point of sale.

Events not appearing in Sitecore Personalize

This issue occurs if you sent an event to Sitecore Personalize and your web browser console contains no errors, but the value for the pointOfSale attribute is incorrect.

To fix the error:

  1. In your script, locate your pointOfSale attributes. Usually, they are either in your settings object or your event data objects, or both.

  2. For every pointOfSale attribute, specify the correct name of a point of sale.

Events related to orders are failing in Sitecore Personalize

This issue occurs if an ADD, CONFIRM, or CHECKOUT event is set up incorrectly.

To fix the error:

  • Make sure that the event data objects for the ADD, CONFIRM, and CHECKOUT events are correctly formatted.

  • Make sure to send the events in the correct sequence.

  • For each item ID included in an object in the product array of the CONFIRM event data object, there must be a preceding ADD event data object where the product item ID is specified in product.item_id.

    See examples.

Release notes

The following table contains Engage JavaScript Library and Engage SDK release notes.

Version

Release notes

1.3.0

Adds the ability to check which version of Sitecore Engage your app is using.

1.2.0

Adds the ability to let the Engage.personalize() function time out.

1.1.0

The Engage SDK now supports server-side tracking.

1.0.0

Adds the ability to:

  • Integrate your application with Sitecore Personalize using a CDN link (Engage JavaScript Library) or the npm package manager (Engage SDK).

  • Collect and send real-time behavioral and transactional data about the users of your app to Sitecore Personalize.

  • Using the Engage SDK, set cookies from the client and from the server.

  • Run personalization. Collect and send behavioral and transactional data that occur inside personalized content.

Boxever JavaScript Library (legacy)

Important

The Boxever JavaScript Library is no longer receiving updates.

If your application uses the Boxever JavaScript Library, we recommend that you upgrade to the Engage JavaScript Library to get future updates and enhancements.

If you are a new customer, use the Engage JavaScript Library or the Engage SDK.

This section describes the most commonly used functions and objects, how to troubleshoot common errors, and release notes for the Boxever JavaScript Library.

Reference

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

The following methods are used in production:

Boxever.eventCreate(event, callback, format)

The eventCreate() function sends an event to Sitecore Personalize. 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 Personalize 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 Personalize. 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 Personalize.

Boxever.callFlows(flow, callback)

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:

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

Boxever.addUTMParams(event)

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

Here's an example of 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:

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

Boxever.browserCreate(object, callback, format)

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:

The following is logged to the console:

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

Boxever.browserShow(browserId, clientKey, callback, format)

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

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.getBucketNumber([callback])

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

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 Personalize 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 Personalize using the getBucketNumber() function and log the bucket number cookie to the console using the getCookie() function.

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

Sitecore Personalize 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 Personalize again using the getBucketNumber() function. Then, you log the bucket number cookie to the console using the getCookie() function:

The bucket number cookie is now different.

Boxever.getClientKey()

The getClientKey() function returns the client key.

Parameters

none

Return value

string

Example

Log the client key to the console:

Boxever.getCookie(cookieName)

The getCookie() functions 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 or number

The name of the cookie.

N/A

Return value

string

Example

Call the getCookie() function:

Boxever.getID()

The getID() function returns the browser ID.

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

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

Parameters

none

Return value

string

Example

Log the browser ID to the console:

Boxever.reset()

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.

Boxever.setCookie(cookieName, cookieValue[, expiresIn])

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

Parameters

Parameter

Type

Description

Note

cookieName

string or number

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.templating()

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.triggerExperiences()

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:

The event object

Important

The Boxever JavaScript Library is no longer receiving updates.

If your application uses the Boxever JavaScript Library, we recommend that you upgrade to the Engage JavaScript Library to get future updates and enhancements.

If you are a new customer, use the Engage JavaScript Library or the Engage SDK.

If you integrate with Sitecore Personalize using the Boxever JavaScript Library or direct HTTP requests, use this event object to collect all the event data about a user's interaction with your application. You then send the event to Sitecore Personalize.

Required attributes

At a minimum, every event data object must include the following attributes. Note that event data objects for different event types may require more attributes than listed in this table.

Attribute

Type

Description

Example

browser_id

string

The browser ID.

If you are using the Boxever JavaScript Library, set the value to the value that the Boxever.getID() function returns: browser_id: Boxever.getID()

If you are using direct HTTP requests, set the value to the value that was returned when you retrieved the browser ID.

The browser ID is a string similar to:

a38b230c-11eb-4cf9-8d5d-274e9f344925​

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

For example, for webpages, the channel is WEB. For mobile app screens, the channel is MOBILE_APP.

Must be one of:

  • AIRPORT_KIOSK

  • BRANCH

  • CALL_CENTER

  • EMAIL

  • GDS

  • KIOSK

  • MOBILE_APP

  • MOBILE_WEB

  • SMS

  • OFFLINE

  • OTA

  • OTHER

  • WEB

type

string (uppercase)

The type of the event that takes place when the user interacts with your brand.

To send a Sitecore Personalize standard event, for example, VIEW or IDENTITY, set the value to a Sitecore Personalize reserved event name.

To send a custom event, set the value to a custom event name of your choice. The custom event name must be different than reserved event namesSitecore Personalize.

Sitecore Personalize reserved event names:

  • myretailsite:CLICKED_POPUP

  • CUSTOM_EVENT_SEARCH

  • CUSTOM_EVENT_BANNER_CLICK

language

string (uppercase ISO 639-1)

The language the user is using your app in.

For example, if the user selects the Japanese language on your website, the language is JA.

  • DE

  • EN

  • FR

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

For example, if the user selects Australian dollars as the currency on your website, the currency is AUD.

  • EUR

  • GBP

  • USD

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

  • home

  • contact-us.html

pos

string

The name of the point of sale where the interaction with your brand takes place.

You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize.

myretailsite/ireland

Event object for VIEW events

The event object for a VIEW event must include all the required attributes for event objects. No further attributes are required.

Example

This example describes an event object for a VIEW event in an integration that uses the Boxever JavaScript Library. The browser_id is set to the value that the Boxever.getID() function returns.

Event object for IDENTITY events

The event object for an IDENTITY event must include all the required attributes for event objects plus the following attributes:

Attribute

Type

Description

Example

Required/optional

identifiers

array of objects

The identity identifiers that are used to identify the users of your app.

identifiers: [{
    "id": "123456",
    "provider": "BXLP"
}]

Required

The identifiers array of objects:

Attribute

Type

Description

Example

Required/optional

id

string

The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.

123456

Required

provider

string

The name of your organization's identity system, external to Sitecore Personalize, that provided the unique guest identifier.

BXLP

Required

expiry_date

string (ISO 8601)

The date the unique guest identifier expires. This is determined by your organization's identity system.

2023-04-15T08:39:44.868Z

Optional

The event object for an IDENTITY event can optionally include personally identifiable information (PII):

Attribute

Type

Description

Example

Required/optional

email

string (lowercase recommended)

The email address of the guest.

jane.doe@myretailsite.com

Optional

title

string (title case)

The title of the guest.

  • Br

  • Brigadier

  • Capt

  • Colonel

  • Dame

  • Dr

  • Elder

  • Fr

  • General

  • Hon

  • Judge

  • Lady

  • Lord

  • Master

  • Miss

  • Mr

  • Mrs

  • Ms

  • Mstr

  • Prof

  • Rabbi

  • Rev

  • Shaikha

  • Sheikh

  • Sir

  • Sister

  • Sr

Optional

firstname

string (title case recommended)

The first name of the guest.

Jane

Optional

lastname

string (title case recommended)

The last name of the guest.

Doe

Optional

gender

string

The gender of the guest.

female

Optional

dob

string (ISO 8601)

The date of birth of the guest.

1983-04-15T08:39:44.868Z

Optional

mobile

string

The mobile number of the guest.

+3531234567

Optional

phone

string

The phone number of the guest.

+3531234567

Optional

street

array of strings (title case recommended)

The street address of the guest.

["Tara Street"]

Optional

city

string (title case recommended)

The city address of the guest.

Dublin

Optional

state

string (title case recommended)

The state address of the guest.

Oregon

Optional

country

string (uppercase ISO 3166-1 alpha-2)

The country address of the guest.

IE

Optional

postal_code

string

The postal code of the guest.

D2

Optional

Example

This example describes an event object for an IDENTITY event in an integration that uses the Boxever JavaScript Library. The browser_id is set to the value that the Boxever.getID() function returns. This event object contains the identifiers array of objects and the following, optional PII attributes: email, firstname, lastname.

Event object for custom events

The event object for a custom event must include all the required attributes for event objects. Set the value of the type attribute to a custom event name of your choice. The custom event name must be different than Sitecore Personalize reserved event names.

You can add custom attributes of your choice.

Example

This example describes an event object for a custom event in an integration that uses the Boxever JavaScript Library. The browser_id is set to the value that the Boxever.getID() function returns.

In the type attribute of the event, the custom event name is specified as myretailsite:CLICKED_POPUP. The event contains the custom attributes clickedPopup and timeBetweenPopupAndClick.

Event object for SEARCH events

The event object for a SEARCH event must include all the required attributes for event objects plus the following attributes:

Attribute

Type

Description

Example

Required/optional

product_type

string

The product type the guest searched for.

This is a custom value of your choice, but note that the value FLIGHT is reserved by Sitecore Personalize. If you set the value to FLIGHT, you must include more attributes in the event object.

  • running shoes

  • office supplies

  • FLIGHT

Required

product_name

string

The product name the guest searched for.

  • airSupport

  • M06P-BLK pencil, 0.6mm

  • DUB-LON

Required

If you set the value of product_type to FLIGHT, the event object for a SEARCH event must also include the following attributes:

Attribute

Type

Description

Example

Required/optional

flight_type

string enum (two-letter, uppercase)

The flight type the guest searched for.

Must be one of:

  • OW

  • RT

OW stands for a one-way flight. RT stands for a return flight.

Required

origin

string (three-letter, uppercase)

The IATA code of the origin the guest searched for.

  • BCN

  • DUB

  • LHR

Required

destination

string (three-letter, uppercase)

The IATA code of the destination the guest searched for.

  • BCN

  • DUB

  • LHR

Required

start

string (ISO 8601) without the time zone. Format: YYYY-MM-DD’T’hh:mm

The local departure date and time of the flight that the guest searched for.

2023-08-21T16:17

Required

end

string (ISO 8601) without the time zone. Format: YYYY-MM-DD’T’hh:mm

The local return date and time of the flight that the guest searched for.

2023-08-23T07:00

Required

adults

integer

The number of adults of the flight the guest searched for.

The minimum value is 0.

2

Required

children

integer

The number of children of the flight the guest searched for.

The minimum value is 0.

2

Required

infants

integer

The number of infants of the flight the guest searched for.

The minimum value is 0.

1

Required

fare_class

string (title case)

The class of flight the guest searched for.

  • Economy

  • Premium Economy

  • Business

  • First Class

Required

fare_family

string (title case recommended)

The fare family of the flight the guest searched for.

  • Economy Plus

  • Flexi Economy

Optional

Examples

This example describes an event object for a SEARCH event in an integration that uses the Boxever JavaScript Library. The browser_id is set to the value that the Boxever.getID() function returns.

This example describes an event object for a SEARCH event in an integration that uses the Boxever JavaScript Library. The browser_id is set to the value that the Boxever.getID() function returns. This event object describes a search for a flight.

The flow object

Important

The Boxever JavaScript Library is no longer receiving updates. We recommend that you upgrade to the Engage JavaScript Library to get future updates and enhancements.

If you integrate with Sitecore Personalize using the Boxever JavaScript Library or direct HTTP requests, use the flow object to collect identifying data about a user, and the friendlyID of an Interactive Full Stack Experience or an Interactive Full Stack Experiment that you want to run for the user. You then send the object to Sitecore Personalize, and Sitecore Personalize runs the experience or experiment.

Required attributes for flow objects

At a minimum, every flow object must include the following attributes plus one guest identifier attribute:

Attribute

Type

Description

Example

Required/optional

clientKey

string

Your client key.

ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe

Required

friendlyId

string

The ID of a live Interactive Full Stack Experience or live Interactive Full Stack Experiment that you want to run.

running_shoes_popup_02

Required

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

For example, for webpages, the channel is WEB. For mobile app screens, the channel is MOBILE_APP.

Must be one of:

  • AIRPORT_KIOSK

  • BRANCH

  • CALL_CENTER

  • EMAIL

  • GDS

  • KIOSK

  • MOBILE_APP

  • MOBILE_WEB

  • SMS

  • OFFLINE

  • OTA

  • OTHER

  • WEB

Required

language

string (uppercase ISO 639-1)

The language the user is using your app in.

For example, if the user selects the Japanese language on your website, the language is JA.

  • DE

  • EN

  • FR

Required

currencyCode

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

For example, if the user selects Australian dollars as the currency on your website, the currency is AUD.

  • EUR

  • GBP

  • USD

Required

pointOfSale

string

The name of the point of sale where the interaction with your brand takes place.

You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize.

  • myretailsite/ireland

Required

In addition to the attributes listed above, the flow object must also include one of the following guest identifier attributes:

Attribute

Type

Description

Example

Required/optional

browserId

string

The browser ID.

If you are using the Boxever JavaScript Library, set the value to the value that the Boxever.getID() function returns: browser_id: Boxever.getID()

If you are using direct HTTP requests, set the value to the value that was returned when you retrieved the browser ID.

The browser ID is a string similar to:

a38b230c-11eb-4cf9-8d5d-274e9f344925​

Required if none of the other attributes in this table are part of the flow object.

email

string (lowercase recommended)

The email address of the guest.

jane.doe@myretailsite.com

Required if none of the other attributes in this table are part of the flow object.

identifiers

array of objects

The identity identifiers that are used to identify the users of your app.

identifiers: [{
    "id": "123456",
    "provider": "BXLP"
}]

Required if none of the other attributes in this table are part of the flow object.

The identifiers array of objects:

Attribute

Type

Description

Example

Required/optional

id

string

The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.

123456

Required

provider

string

The name of your organization's identity system, external to Sitecore Personalize, that provided the unique guest identifier.

BXLP

Required

expiry_date

string (ISO 8601)

The date the unique guest identifier expires. This is determined by your organization's identity system.

2023-04-15T08:39:44.868Z

Optional

Optional attributes for flow objects

The flow object can optionally contain custom objects of your choice:

Attribute

Type

Description

Example

Required/optional

params

object

An object of your choice.

params: { key: "value" }

Optional

Examples

This example describes a flow object in an integration that uses the Boxever JavaScript Library. The flow object uses the browserId as the guest identifier. It also contains optional custom objects.

This example describes a flow object in an integration that uses the Boxever JavaScript Library. The flow object uses the email as the guest identifier.

This example describes a flow object in an integration that uses the Boxever JavaScript Library. The flow object uses the identifiers array of objects as the guest identifier.

Troubleshooting

This topic describes the most common errors and solutions when integrating using the Boxever JavaScript Library.

401 Unauthorized error when trying to load the library

This error occurs when the value for the client_key key or the value for the target key is incorrect in the library script.

To fix the error:

  1. Locate your library script.

  2. For the client_key key, specify the correct client key.

  3. For the target key, specify the correct Stream API target endpoint.

403 Forbidden error when trying to load the library

This error occurs when the value for the javascriptLibraryVersion key or for the web_flow_target key is incorrect in the library script.

To fix the error:

  1. Locate your library script.

  2. For the javascriptLibraryVersion key, set the value to "1.4.9".

  3. For the web_flow_target key, depending on whether your organization uses Sitecore Personalize, specify the correct web flow target.

    The web flow target is the path for the Amazon CloudFront CDN for Sitecore Personalize.

    Scenario

    Web flow target

    Your organization uses Sitecore Personalize.

    https://d35vb5cccm4xzp.cloudfront.net

    Your organization does not use Sitecore Personalize.

    An empty string ""

400 Bad request error when trying to send an event

This error occurs when the event object does not contain a type.

To fix the error:

  1. In your library script, locate all event objects.

  2. Make sure each each event object contains a type.

404 Not Found error when trying to send an event

This error occurs when the event object contains the incorrect browser ID.

To fix the error:

  1. In your library script, locate all event objects.

  2. Make sure each event object contains a browser_id.

  3. Set the value of browser_id to the value that the Boxever.getID() function returns: browser_id: Boxever.getID().

Events not appearing in Sitecore Personalize

If you sent an event to Sitecore Personalize and your web browser console contains no errors, this issue occurs if the value for the pointOfSale key is incorrect.

To fix the error:

  1. In your library script, locate all event objects.

  2. For the pointOfSale key, specify the correct name of a point of sale.

Web Experiences load too slow on my website

If a Web Experience or a Web Experiment takes too long to display after your webpage loads, consider loading the library script as early in your code as possible.

Flicker when loading Web Experiments

If a Web Experiment loads with flicker, consider loading the library script as early in your code as possible.

Preview API not working

If you are working in Sitecore Personalize with the Preview API for a Web Experience or Web Experiment, the Preview API does not work if the value for the web_flow_target key is incorrect in the library script.

To fix the error:

  1. Locate your library script.

  2. For the web_flow_target key, specify the correct web flow target.

    The web flow target is the path for the Amazon CloudFront CDN for Sitecore Personalize.

    Scenario

    Web flow target

    Your organization uses Sitecore Personalize.

    https://d35vb5cccm4xzp.cloudfront.net

    Your organization does not use Sitecore Personalize.

    An empty string ""

Release notes

The following table contains Boxever JavaScript Library releases.

Version

Release notes

1.4.9

Includes the optional web_flow_config setting that lets you disable the asynchronous loading of the Web Experiences library (lib.js) and/or defer script loading until the DOM is fully built. This is facilitated through the Boxever JavaScript Library. It loads version.js library to get the latest version and then loads lib.js library. This is only for organizations that use web experiments or web experiences in Sitecore Personalize.

1.4.8

Adds compatibility with v1.3 Browser Service. Removes support for Internet Explorer 11.

1.4.6

Includes the optional _boxever_settings.itp_cross_domain setting, which automatically applies the cross-domain setting only for Intelligent Tracking Prevention (ITP) browsers, most commonly Safari. Also contains a bug fix for the _boxever_settings.cookie_expiry_in_days property to ensure the days attribute is honored for customized cookie expiry and local storage expiry.

1.4.5

If the _boxever_settings.cross_domain property is enabled, the _boxever_settings.cookie_domain is ignored. This applies to organizations that use cross-domain support, by ensuring that the browser does not reject the cookie if the domain setting does not match.

1.4.4

Removes support of the eval() function from the Boxever JavaScript Library. The eval() function runs JavaScript code represented as a string, which might be a security risk. Removes support of Internet Explorer 8. Renames the init property to boxeverInit property to avoid potential naming conflicts with other libraries.

1.4.3

Adds the _boxever_settings.cookies_only property that provides the option to only set cookies and disable local storage for data capture. We do not recommend this for data capture. Local storage is now only set when it is being used. Previous to version 1.4.3, the Boxever JavaScript Library bootstrapped an empty object ({}) in localstorage with the intention of being written into.

1.4.2

Adds the _boxever_settings.cookie_expiry_in_days property that provides the option to customize cookie and local storage expiry.

1.4.1

Supports web optimization and experiences production releases.

1.3.6

Introduces local storage to work alongside cookies for data capture. This is to account for versions of Safari 12+ with Safari Intelligent Tracking Prevention (ITP), the privacy feature that allows the Safari web browser to block cookies in Safari 12+ versions.

Direct HTTP requests

If you integrate with Sitecore Personalize using direct HTTP requests, use this reference for formatting your requests. Every parameter and attribute is required unless marked as optional.

Base URL

The base URL is determined by the environment of your Sitecore Personalize instance.

To find the environment, in Sitecore Personalize, on the navigation pane, click cdp_gear_icon.png > Company information > Environment.

Environment

Base URL

AP Region

https://api-engage-ap.sitecorecloud.io​

EU Region

https://api-engage-eu.sitecorecloud.io

US Region

https://api-engage-us.sitecorecloud.io

You must send each request over HTTPS. HTTP is not supported.

Authentication

To make direct HTTP requests to the Stream API, you must include your Sitecore Personalize client key as a query string parameter in the URI of the request.

Example 30. Sending a client key with a request when retrieving the browser ID
curl -X GET -g 'https://api.boxever.com/v1.2/browser/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe'
curl -X GET -g 'https://api.boxever.com/v1.2/browser/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe'

Retrieve the browser ID

GET /v1.2/browser/create.json?client_key=client_key

Retrieves the browser ID from Sitecore Personalize using the Browser API (Stream API type). In the response, the ref key contains the browser ID.

You must include the browser ID in every follow-up request that you make to Sitecore Personalize.

Parameters

Parameter

Type

Description

Example

client_key

string

Your client key.

ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe

Request
curl -X GET -g 'https://api.boxever.com/v1.2/browser/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe'
Request
curl -X GET -g 'https://api.boxever.com/v1.2/browser/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe'
Response
json
{
    "status": "OK",
    "version": "1.2",
    "client_key": "ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe",
    "ref": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "customer_ref": "f7aabbca-1c1b-4fc2-be72-3e16294a4f03"
}

Sending events

Note

Instead of using direct HTTP requests, we recommend that you send events using the Engage JavaScript Library or the Engage SDK. Using the Engage JavaScript Library or the Engage SDK, you have to format and send your event data differently than described in this section. See Sending events.

GET /v1.2/event/create.json?client_key=client_key&message=event

To send events to Sitecore Personalize using direct HTTP requests, for example, a VIEW event, make GET requests using the Event API (Stream API type). Pass the event object in the message parameter. Make sure to format the event object correctly and to include all the required attributes.

Using direct HTTP requests, you can send the following events:

Parameters

Parameter

Type

Description

Example

client_key

string

Your client key.

ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe

event

JSON object

All the event details.

{"key1":"value","key2":"value"}

Format of event objects

The event data is sent as a JSON object in the URL. Attend to the following:

  • Wrap the object in curly braces {}.

  • Wrap every key and every value in double quotes "".

  • Don't add line breaks.

  • Don't add spaces around keys and around values.

Required attributes

At a minimum, every event data object must include the following attributes. Note that event data objects for different event types may require more attributes than listed in this table.

Attribute

Type

Description

Example

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

For example, for webpages, the channel is WEB. For mobile app screens, the channel is MOBILE_APP.

Must be one of:

  • AIRPORT_KIOSK

  • BRANCH

  • CALL_CENTER

  • EMAIL

  • GDS

  • KIOSK

  • MOBILE_APP

  • MOBILE_WEB

  • SMS

  • OFFLINE

  • OTA

  • OTHER

  • WEB

type

string (uppercase)

The type of the event that takes place when the user interacts with your brand.

To send a Sitecore Personalize standard event, for example, VIEW or IDENTITY, set the value to a Sitecore Personalize reserved event name.

To send a custom event, set the value to a custom event name of your choice. The custom event name must be different than Sitecore Personalize reserved event names.

Sitecore Personalize reserved event names:

  • myretailsite:CLICKED_POPUP

  • CUSTOM_EVENT_SEARCH

  • CUSTOM_EVENT_BANNER_CLICK

language

string (uppercase ISO 639-1)

The language the user is using your app in.

For example, if the user selects the Japanese language on your website, the language is JA.

  • DE

  • EN

  • FR

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

For example, if the user selects Australian dollars as the currency on your website, the currency is AUD.

  • EUR

  • GBP

  • USD

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

  • home

  • contact-us.html

pos

string

The name of the point of sale where the interaction with your brand takes place.

You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize.

myretailsite/ireland

browser_id

string

The browser ID.

The browser ID is a string similar to:

a38b230c-11eb-4cf9-8d5d-274e9f344925​

Example 31. Correctly formatted event object for a VIEW event
{"channel":"MOBILE_APP","type":"VIEW","language":"EN","currency":"EUR","page":"homepage","pos":"myretailsite/ireland","browser_id":"a38b230c-11eb-4cf9-8d5d-274e9f344925​"}
{"channel":"MOBILE_APP","type":"VIEW","language":"EN","currency":"EUR","page":"homepage","pos":"myretailsite/ireland","browser_id":"a38b230c-11eb-4cf9-8d5d-274e9f344925​",}
Request
curl -X GET -g 'https://api.boxever.com/v1.2/event/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe&message={"channel":"MOBILE_APP","type":"VIEW","language":"EN","currency":"EUR","page":"homepage","pos":"myretailsite/ireland","browser_id":"a38b230c-11eb-4cf9-8d5d-274e9f344925​"}'
Request
curl -X GET -g 'https://api.boxever.com/v1.2/event/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe&message={"channel":"MOBILE_APP","type":"VIEW","language":"EN","currency":"EUR","page":"homepage","pos":"myretailsite/ireland","browser_id":"a38b230c-11eb-4cf9-8d5d-274e9f344925​"}'
Response
json
{
    "status": "OK",
    "version": "1.2",
    "client_key": "ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe",
    "ref": "dcb27c41-688d-4c36-8ed7-536e7bf590ba"
}

VIEW event

The VIEW event captures the user's action of viewing a page in your application. It triggers every time your webpage loads. You must send VIEW events from all webpages where you want to track user behavior.

We recommend that you capture a VIEW event on the following webpage types:

  • Home

  • Search results

  • Product description

  • Payment

  • Confirmation

  • Promotional offers

To send a VIEW event, use the following required attributes:

Attribute

Type

Description

Example

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

  • MOBILE_APP

  • MOBILE_WEB

  • WEB

type

string (uppercase)

The type of the event that takes place when the user interacts with your brand.

VIEW

language

string (uppercase ISO 639-1)

The language the user is using your app in.

  • DE

  • EN

  • FR

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

  • EUR

  • GBP

  • USD

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

  • home

  • contact-us.html

pos

string

The name of the point of sale where the interaction with your brand takes place.

  • myretailsite/ireland

  • spinair.com/france

browser_id

string

The browser ID.

a38b230c-11eb-4cf9-8d5d-274e9f344925​

Example 32. VIEW event object
{
    "channel": "MOBILE_APP",
    "type": "VIEW",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​"
}
{
    "channel": "MOBILE_APP",
    "type": "VIEW",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​"
}

Session data

You can capture session data in an event that is triggered in the session, for example, a VIEW event or an ADD event. To pass session data in a custom-made deep link, place the deep link in the object.

Attribute

Type

Description

Example

Required/optional

sessionData

JSON object

JSON Object An object of arbitrary session data.

N/A

Required

sessionData.attribute

Any of the following:

  • string

  • boolean

  • integer

  • float

One or many name/value pair attributes for custom session data.

"is_logged_in":true

Optional

Example 33. Session data
{
    "channel": "MOBILE_APP",
    "type": "VIEW",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "sessionData": {  
        "deep_link": "https://www.retailsite123.com/search?product=shoes",
        "is_logged_in": true,
        "assistance": false
     }
}
{
    "channel": "MOBILE_APP",
    "type": "VIEW",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "sessionData": {  
        "deep_link": "https://www.retailsite123.com/search?product=shoes",
        "is_logged_in": true,
        "assistance": false
     }
}

Tracking data

You can capture tracking data in the form of Urchin Tracking Module (UTM) parameters when you send a VIEW event. The VIEW event is the only event type you can use to capture tracking data.

Example 34. A URL containing UTM parameters
https://myretailsite.com?utm_source=newsletter&utm_medium=email&utm_campaign=summer_sale&utm_term=running+shoes
https://myretailsite.com?utm_source=newsletter&utm_medium=email&utm_campaign=summer_sale&utm_term=running+shoes
Example 35. VIEW event object with UTM parameters included
{ 
    "channel": "MOBILE_APP",
    "type": "VIEW",
    "language": "EN",
    "currency": "EUR",
    "page": "home",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "summer_sale",
    "utm_term": "running shoes"
}
{ 
    "channel": "MOBILE_APP",
    "type": "VIEW",
    "language": "EN",
    "currency": "EUR",
    "page": "home",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "summer_sale",
    "utm_term": "running shoes"
}

IDENTITY event

Example 36. IDENTITY event object with identifiers
{
    "channel": "MOBILE_APP",
    "type": "IDENTITY",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "identifiers": [{
        "provider": "BXLP",
        "id": "123456"
    }]
}
{
    "channel": "MOBILE_APP",
    "type": "IDENTITY",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "identifiers": [{
        "provider": "BXLP",
        "id": "123456"
    }]
}
Example 37. IDENTITY event object with identifiers and personally identifiable information (PII)
{
    "channel": "MOBILE_APP",
    "type": "IDENTITY",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "identifiers": [
        {
            "id": "123456",
            "provider": "BXLP"
        }
    ],
    "email": "jane.doe@myretailsite.com",
    "firstname": "Jane",
    "lastname": "Doe"
}
Example 38. IDENTITY event object with personally identifiable information (PII)
{
    "channel": "MOBILE_APP",
    "type": "IDENTITY",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "email": "jane.doe@myretailsite.com",
    "title": "Ms",
    "firstname": "Jane",
    "lastname": "Doe",
    "gender": "female",
    "dob": "1980-01-23T00:00",
    "passport_no": "IR123456",
    "mobile": "+3531234567",
    "phone": "+3531234567",
    "street": ["Ashford House", "Tara Street", "Dublin 2"],
    "city": "Dublin",
    "country": "IE",
    "postal_code": "D2",
    "identifiers": [{
        "provider": "BXLP",
        "id": "123456"
    }]
}

SEARCH event

The SEARCH event captures the user's action of searching for a product. You must send the SEARCH event to Sitecore Personalize when the search results page loads.

Example 39. SEARCH event object
{
    "channel": "MOBILE_APP",
    "type": "SEARCH",
    "language": "EN",
    "currency": "EUR",
    "page": "search result page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product_name": "airSupport",
    "product_type": "RUNNERS"
}
{
    "channel": "MOBILE_APP",
    "type": "SEARCH",
    "language": "EN",
    "currency": "EUR",
    "page": "search result page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product_name": "airSupport",
    "product_type": "RUNNERS"
}
Example 40. SEARCH event object for flight search
{
    "channel": "MOBILE_APP",
    "type": "SEARCH",
    "language": "EN",
    "currency": "EUR",
    "page": "search result page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product_name": "DUB-LHR",
    "product_type": "FLIGHT",
    "flight_type": "RT",
    "origin": "DUB",
    "destination": "LHR",
    "start": "2023-01-30T00:00",
    "end": "2023-02-01T00:00",
    "adults": 1,
    "children": 0,
    "infants": 0,
    "fare_class": "Economy",
    "fare_family": "Economy Plus"
}
{
    "channel": "MOBILE_APP",
    "type": "SEARCH",
    "language": "EN",
    "currency": "EUR",
    "page": "search result page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product_name": "DUB-LHR",
    "product_type": "FLIGHT",
    "flight_type": "RT",
    "origin": "DUB",
    "destination": "LHR",
    "start": "2023-01-30T00:00",
    "end": "2023-02-01T00:00",
    "adults": 1,
    "children": 0,
    "infants": 0,
    "fare_class": "Economy",
    "fare_family": "Economy Plus"
}

ADD event

The ADD event captures the product details when a user adds the product(s) to their online cart.

Example 41. ADD event object
{
   "channel": "MOBILE_APP",
   "type": "ADD",
   "language": "EN",
   "currency": "EUR",
   "page": "races",
   "pos": "myretailsite/ireland",
   "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
   "product": {
      "type": "BET",
      "item_id": "EXACT_90",
      "name": "Exact score after 90 minutes",
      "orderedAt": "2023-08-23T16:17:16.000Z",
      "quantity": 1,
      "price": 100.00,
      "productId": "CORRECT_SCORE",
      "currency": "EUR",
      "originalPrice": 100.00,
      "originalCurrencyCode": "EUR",
      "referenceId": "BET_001-1"
   }
}
{
   "channel": "MOBILE_APP",
   "type": "ADD",
   "language": "EN",
   "currency": "EUR",
   "page": "races",
   "pos": "myretailsite/ireland",
   "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
   "product": {
      "type": "BET",
      "item_id": "EXACT_90",
      "name": "Exact score after 90 minutes",
      "orderedAt": "2023-08-23T16:17:16.000Z",
      "quantity": 1,
      "price": 100.00,
      "productId": "CORRECT_SCORE",
      "currency": "EUR",
      "originalPrice": 100.00,
      "originalCurrencyCode": "EUR",
      "referenceId": "BET_001-1"
   }
}
Example 42. ADD event object for a flight
{
    "channel": "MOBILE_APP",
    "type": "ADD",
    "language": "EN",
    "currency": "EUR",
    "page": "itinerary page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": {
        "type": "FLIGHT",
        "item_id": "FLIGHT_1",
        "name": "DUB-LHR Economy Flight",
        "currency": "EUR",
        "price": 200,
        "product_id": "DUB-LHR|Economy|EconomyPlus",
        "origin": "DUB",
        "destination": "LHR",
        "flight_type": "OW",
        "pax_type": "ADT",
        "quantity": 1,
        "flight_segment": [{
            "origin": "DUB",
            "destination": "LHR",
            "departure_date_time": "2023-01-14T06:30",
            "arrival_date_time": "2023-01-14T07:50",
            "flight_number": "1000",
            "carrier": "SA",
            "fare_class": "Economy",
            "fare_family": "Economy Plus"
        }]
    }
}
{
    "channel": "MOBILE_APP",
    "type": "ADD",
    "language": "EN",
    "currency": "EUR",
    "page": "itinerary page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": {
        "type": "FLIGHT",
        "item_id": "FLIGHT_1",
        "name": "DUB-LHR Economy Flight",
        "currency": "EUR",
        "price": 200,
        "product_id": "DUB-LHR|Economy|EconomyPlus",
        "origin": "DUB",
        "destination": "LHR",
        "flight_type": "OW",
        "pax_type": "ADT",
        "quantity": 1,
        "flight_segment": [{
            "origin": "DUB",
            "destination": "LHR",
            "departure_date_time": "2023-01-14T06:30",
            "arrival_date_time": "2023-01-14T07:50",
            "flight_number": "1000",
            "carrier": "SA",
            "fare_class": "Economy",
            "fare_family": "Economy Plus"
        }]
    }
}

ADD event for flight

2.1 data model

The ADD event sends product data to a large number of data points for both decisioning and for populating content into the abandoned cart email message.

When sending multiple ADD events, you must send them in the correct order. For example, for a DUB to LHR return flight, first send the ADD event for DUB-LHR, then in the callback send the ADD event for LHR-DUB.

Attribute

Description

Type

Example(s)

Required/optional

channel

The channel captured on each page the guest visited.

string

WEB", "MOBILE_WEB", "MOBILE_APP"

Required

type

The type of event.

string (uppercase)

"ADD"

Required

language

The language captured on each page the guest visited.

string (2 letter ISO 639 language code)

"EN", "FR", "DE"

Required

currency

The type of currency.

string (3 letter ISO 4217)

"EUR", "USD", "GBP"

Required

page

The name of the webpage the guest visited.

string

"home page", "search page" "/home", "/confirm"

Required

pos

The point of sale (storefront) captured on each page the guest visited.

string (predefined by client)

"flightspin.com", "spinair.com"

Required

browser_id

The ID of a browser generated by Sitecore Personalize.

string (UUID)

"56860bff-94ba-4d84-aa37-2b5a83d5411b"

Required

product

The JSON object that contains the product entity data.

JSON object

N/A

Required

product.type

The type of product added to cart.

string (uppercase)

"FLIGHT"

Required

product.item_id

The item ID of the product added to the cart. Used in ETL to create the order.

string

"FLIGHT_1"

Required

product.name

The name of the product added to the cart.

string (suggest title case)

"DUB-LHR Economy Flight"

Required

product.currency

The currency of the product added to the cart.

string (3 letter ISO 4217)

"EUR", "USD", "NZD"

Required

product.price

The unit price of the product. Total price of the product is calculated by unit price multiplied by quantity.

number

20, 1000.5

Required

product.quantity

The number of unit added. Total price of the product is calculated by unit price multiplied by quantity.

integer

2

Required

product.product_id

The product ID of the product added. Used in Analytics for reporting.

string (suggest title case)

"DUB-LHR|Economy|EconomyPlus"

Required

product.origin

The IATA code (airport only) of the flight origin.

string (IATA airport code)

"DUB", "LHR", "BCN"

Required

product.destination

The IATA code (airport only) of the flight destination.

string (IATA airport code)

"DUB", "LHR", "BCN"

Required

product.flight_type

The type of flight.

string (uppercase)

"OW" for One way, "RT" for Return

Required

product.pax_type

The passenger type of flight ticket.

string (uppercase)

"ADT" for adult, "CHD" for child, "INF" for infant

Required

product.flight_segment

The JSON object that contains the flight segment entity data.

JSON object

N/A

Required

product.flight_segment.origin

The IATA code (airport only) of the flight segment origin.

string (IATA airport code)

"DUB", "LHR", "BCN"

Required

product.flight_segment.destination

The IATA code (airport only) of the flight segment destination.

string (IATA airport code)

"DUB", "LHR", "BCN"

Required

product.flight_segment.departure_date_time

The local departure date and time of the flight segment.

string "YYYY-MM-DD’T’hh:mm" ISO 8601 Date/Time local time without timezone

"2016-08-21T16:17"

Required

product.flight_segment.arrival_date_time

The local arrival date and time of the flight segment.

string "YYYY-MM-DD’T’hh:mm" ISO 8601 Date/Time local time without timezone

"2016-08-23T07:00"

Required

product.flight_segment.flight_number

The number of the carrier.

string

"1230"

Required

product.flight_segment.carrier

The marketing carrier code of the flight segment.

2 character IATA carrier code (uppercase)

"EI", "FR", "BA"

Required

product.flight_segment.fare_class

The fare class of the flight segment.

string (title case)

"Economy", "Premium Economy", "Business", "First Class"

Required

product.flight_segment.equipment_type

The equipment type relevant to the flight segment.

string

"A380", "B774", "A310"

Optional

product.flight_segment.fare_family

The fare family of the flight segment.

string (suggest title case)

"Economy Plus", "Flexi Economy"

Optional

{
    "channel": "WEB",
    "type": "ADD",
    "language": "EN",
    "currency": "EUR",
    "page": "itinerary page",
    "pos": "spinair.com",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": {
        "type": "FLIGHT",
        "item_id": "FLIGHT_1",
        "name": "DUB-LHR Economy Flight",
        "currency": "EUR",
        "price": 200,
        "product_id": "DUB-LHR|Economy|EconomyPlus",
        "origin": "DUB",
        "destination": "LHR",
        "flight_type": "OW",
        "pax_type": "ADT",
        "quantity": 1,
        "flight_segment": [{
            "origin": "DUB",
            "destination": "LHR",
            "departure_date_time": "2015-01-14T06:30",
            "arrival_date_time": "2015-01-14T07:50",
            "flight_number": "1000",
            "carrier": "SA",
            "fare_class": "Economy",
            "fare_family": "Economy Plus"
        }]
    }
}

ADD event for ancillary product

You can use the ADD event to capture ancillary products that the user adds to their cart, such as insurance. This event is optional, but employing it can positively affect the amount of available data. Using this event is the only way to capture ancillary products that the user adds to their cart. This event also helps ensure accuracy of the cart contents and order values when a user returns to their abandoned cart.

Example 43. ADD event object for ancillary product
{
    "channel": "MOBILE_APP",
    "type": "ADD",
    "language": "EN",
    "currency": "EUR",
    "page": "passengers page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": {
        "type": "BAG",
        "item_id": "BAG_1",
        "name": "20kg Bag",
        "currency": "EUR",
        "price": 10,
        "product_id": "Bag20",
        "quantity": 1
    }
}
{
    "channel": "MOBILE_APP",
    "type": "ADD",
    "language": "EN",
    "currency": "EUR",
    "page": "passengers page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": {
        "type": "BAG",
        "item_id": "BAG_1",
        "name": "20kg Bag",
        "currency": "EUR",
        "price": 10,
        "product_id": "Bag20",
        "quantity": 1,
        "linked_consumer_reference_ids": ["CONSUMER_1", "CONSUMER_2"]
    }
}

ADD_CONSUMERS event

Use the ADD_CONSUMERS event to capture the guest's action of adding consumers to the product. Each consumer is associated to a guest. A consumer can be a traveller guest_type (if there is insufficient identity information). Alternatively, a consumer can be a customer guest_type if there is sufficient identity information on the current order and there is a previous order.

To send an ADD_CONSUMERS event, use the following required attributes:

Attribute

Type

Description

Example

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

  • MOBILE_APP

  • MOBILE_WEB

  • WEB

type

string (uppercase)

The type of the event that takes place when the user interacts with your brand.

VIEW

language

string (uppercase ISO 639-1)

The language the user is using your app in.

  • DE

  • EN

  • FR

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

  • EUR

  • GBP

  • USD

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

  • home

  • contact-us.html

pos

string

The name of the point of sale where the interaction with your brand takes place.

  • myretailsite/ireland

  • spinair.com/france

browser_id

string

The browser ID.

a38b230c-11eb-4cf9-8d5d-274e9f344925​

consumer

array of objects

The consumer data.

N/A

The consumer array of objects:

Attribute

Type

Description

Example

Required/optional

title

string (title case)

The title of the consumer.

  • Br

  • Brigadier

  • Capt

  • Colonel

  • Dame

  • Dr

  • Elder

  • Fr

  • General

  • Hon

  • Judge

  • Lady

  • Lord

  • Master

  • Miss

  • Mr

  • Mrs

  • Ms

  • Mstr

  • Prof

  • Rabbi

  • Rev

  • Shaikha

  • Sheikh

  • Sir

  • Sister

  • Sr

Required

firstname

string (title case recommended)

The first name of the consumer.

Jane

Required

lastname

string (title case recommended)

The last name of the consumer.

Doe

Required

gender

string

The gender of the consumer.

female

Optional

dob

string (ISO 8601)

The date of birth of the consumer.

1983-04-15T08:39:44.868Z

Optional

mobile

string

The mobile number of the consumer.

+3531234567

Optional

nationality

string (title case)

The nationality of the consumer.

  • Irish

  • Spanish

  • Chinese

Optional

reference_id

string

The reference ID of the consumer.

  • "1"

  • "2"

Optional

item_id

array of strings

A list of item IDs of core and dependent products that belong to the consumer.

["FLIGHT_1", "FLIGHT_2", "BAG_1", "SEAT_1" "HOTEL_1"]

Optional

Example 44. ADD_CONSUMERS event object
{
    "channel": "MOBILE_APP",
    "type": "ADD_CONSUMERS",
    "language": "EN",
    "currency": "EUR",
    "page": "payment page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "consumer": [{
        "title": "Mr",
        "firstname": "Jack",
        "lastname": "Smith",
        "dob": "1975-04-23T00:00",
        "gender": "male",
        "mobile": "+353123456",
        "nationality": "Irish",
        "reference_id": "1",
        "item_id": [
            "FLIGHT_1",
            "FLIGHT_2",
            "BAG_1",
            "SEAT_1"
        ]
    }, {
        "title": "Ms",
        "firstname": "Lily",
        "lastname": "Smith",
        "dob": "1980-01-15T00:00",
        "gender": "female",
        "mobile": "+353123458",
        "nationality": "Irish",
        "reference_id": "2",
        "item_id": [
            "FLIGHT_1",
            "FLIGHT_2",
            "BAG_2",
            "SEAT_2"
        ]
    }]   
}
{
    "channel": "MOBILE_APP",
    "type": "ADD_CONSUMERS",
    "language": "EN",
    "currency": "EUR",
    "page": "payment page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "consumer": [{
        "title": "Mr",
        "firstname": "Jack",
        "lastname": "Smith",
        "dob": "1975-04-23T00:00",
        "gender": "male",
        "mobile": "+353123456",
        "nationality": "Irish",
        "reference_id": "1",
        "item_id": [
            "FLIGHT_1",
            "FLIGHT_2",
            "BAG_1",
            "SEAT_1"
        ]
    }, {
        "title": "Ms",
        "firstname": "Lily",
        "lastname": "Smith",
        "dob": "1980-01-15T00:00",
        "gender": "female",
        "mobile": "+353123458",
        "nationality": "Irish",
        "reference_id": "2",
        "item_id": [
            "FLIGHT_1",
            "FLIGHT_2",
            "BAG_2",
            "SEAT_2"
        ]
    }]   
}

ADD_CONTACTS event

Example 45. ADD_CONTACTS event object
{
   "channel": "MOBILE_APP",
   "type": "ADD_CONTACTS",
   "language": "EN",
   "currency": "EUR",
   "page": "home page",
   "pos": "myretailsite/ireland",
   "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
   "contact": [
      {
         "title": "Mr",
         "firstname": "Jack",
         "lastname": "Smith",
         "mobile": "(+353)1234567",
         "phone": "(+353)1234568",
         "street": [
            "123 Fake Street"
         ],
         "city": "Dublin",
         "country_code": "IE",
         "postal_code": "1234",
         "dob": "1975-04-23T00:00",
         "email": "jack.smith@gmail.com",
         "gender": "male",
         "identifiers": [
            {
               "provider": "BXLP",
               "id": "123456",
               "expiryDate": "2023-01-01T16:17:16.000Z",
            }
         ]
      }
   ]
}
{
    "channel": "MOBILE_APP",
    "type": "ADD_CONTACTS",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "contact": [{
        "title": "Mr",
        "firstname": "Jack",
        "lastname": "Smith",
        "mobile": "(+353)1234567",
        "phone": "(+353)1234568",
        "street": ["123 Fake Street"],
        "city": "Dublin",
        "country_code": "IE",
        "postal_code": "1234",
        "dob": "1975-04-23T00:00",
        "email": "jack.smith@boxever.com",
        "gender": "male"
    }]
}

CONFIRM event

The CONFIRM event captures the confirmation of purchased products. It is a vector of the products that are confirmed to be in the cart before the payment is made.

To send a CONFIRM event, use the following required attributes:

Example 46. CONFIRM event object
{
    "channel": "MOBILE_APP",
    "type": "CONFIRM",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": [
        {"item_id": "SHOES_8475GHT"},
        {"item_id": "TSHIRT_XLGRN"}
    ]
}
{
    "channel": "MOBILE_APP",
    "type": "CONFIRM",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": [
        {"item_id": "SHOES_8475GHT"},
        {"item_id": "TSHIRT_XLGRN"}
    ]
}
Example 47. CONFIRM event object for a flight
{
    "channel": "MOBILE_APP",
    "type": "CONFIRM",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": [
        {"item_id": "FLIGHT_1"},
        {"item_id": "FLIGHT_2"},
        {"item_id": "BAG_1"},
        {"item_id": "SEAT_1"}
    ]
}
{
    "channel": "MOBILE_APP",
    "type": "CONFIRM",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": [
        {"item_id": "FLIGHT_1"},
        {"item_id": "FLIGHT_2"},
        {"item_id": "BAG_1"},
        {"item_id": "SEAT_1"}
    ]
}

CONFIRM event for flights

2.1 data model

Attribute

Description

Type

Example(s)

Required/optional

channel

The channel captured on each page the guest visited.

string (uppercase)

"WEB", "MOBILE_WEB", "MOBILE_APP"

Required

type

The type of event.

string (uppercase)

"CONFIRM"

Required

language

The language captured on each page the Guest visited.

string (2 letter ISO 639 language code)

"EN", "FR", "DE"

Required

currency

The type of currency.

string (3 letter ISO 4217)

"EUR", "USD", "GBP"

Required

page

The name of the webpage the guest visited.

string

"home page", "search page" "/home", "/confirm"

Required

pos

The point of sale (storefront) captured on each page the guest visited.

string (predefined by the client)

"spinflight.com", "spinair.com"

Required

browser_id

The ID of a browser generated by Sitecore Personalize.

string (UUID)

"56860bff-94ba-4d84-aa37-2b5a83d5411b"

Required

product

A JSON array containing a list of item_id objects.

JSON array

[{ "item_id": "FLIGHT_1" }, { "item_id": "FLIGHT_2" }, { "item_id": "BAG_1" }, { "item_id": "SEAT_1" }]

Required

product.item_id

The item ID of the product to be confirmed as purchased.

string

"FLIGHT_1"

Required

2.0 data model

Attribute

Description

Type

Example(s)

Required/optional

channel

The channel captured on each page the guest visited.

string (uppercase)

"WEB", "MOBILE_WEB", "MOBILE_APP"

Required

type

The type of event.

string (uppercase)

"CONFIRM"

Required

language

The language captured on each page the Guest visited.

string (2 letter ISO 639 language code)

"EN", "FR", "DE"

Required

currency

The type of currency.

string (3 letter ISO 4217)

"EUR", "USD", "GBP"

Required

page

The name of the webpage the guest visited.

string

"home page", "search page" "/home", "/confirm"

Required

pos

The point of sale (storefront) captured on each page the guest visited.

string (predefined by the client)

"spinflight.com", "spinair.com"

Required

browser_id

The ID of a browser generated by Sitecore Personalize.

string (UUID)

"56860bff-94ba-4d84-aa37-2b5a83d5411b"

Required

product

A JSON array containing a list of item_id objects.

JSON array

[{ "item_id": "FLIGHT_1" }, { "item_id": "FLIGHT_2" }, { "item_id": "BAG_1" }, { "item_id": "SEAT_1" }]

Required

product.item_id

The item ID of the product to be confirmed as purchased.

string

"FLIGHT_1"

Required

{
    "channel": "WEB",
    "type": "CONFIRM",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": [{
        "item_id": "FLIGHT_1"
    }, {
        "item_id": "FLIGHT_2"
    }, {
        "item_id": "BAG_1"
    }, {
        "item_id": "SEAT_1"
    }]
}
{
    "channel": "MOBILE_APP",
    "type": "CONFIRM",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "product": [{
        "item_id": "FLIGHT_1"
    }, {
        "item_id": "FLIGHT_2"
    }, {
        "item_id": "BAG_1"
    }, {
        "item_id": "SEAT_1"
    }]
}

CHECKOUT event

The CHECKOUT event captures a guest's action of checking out an order. After you send this event, you can view the event in the guest profile.

To send a CHECKOUT event, use the following required attributes:

Attribute

Type

Description

Example

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

  • MOBILE_APP

  • MOBILE_WEB

  • WEB

type

string (uppercase)

The type of the event that takes place when the user interacts with your brand.

VIEW

language

string (uppercase ISO 639-1)

The language the user is using your app in.

  • DE

  • EN

  • FR

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

  • EUR

  • GBP

  • USD

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

  • home

  • contact-us.html

pos

string

The name of the point of sale where the interaction with your brand takes place.

  • myretailsite/ireland

  • spinair.com/france

browser_id

string

The browser ID.

a38b230c-11eb-4cf9-8d5d-274e9f344925​

reference_id

string (uppercase)

The reference of the order.

ABC123

status

string enum

The status of the order.

  • PURCHASED

  • PAYMENT_PENDING

  • CONFIRMED

  • REFUNDED

  • CANCELLED

Example 48. CHECKOUT event object
{
    "channel": "MOBILE_APP",
    "type": "CHECKOUT",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "reference_id": "ABC123",
    "status": "PURCHASED"
}
{
    "channel": "MOBILE_APP",
    "type": "CHECKOUT",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "reference_id": "ABC123",
    "status": "PURCHASED"
}

ORDER_CHECKOUT event

Example 49. ORDER_CHECKOUT event object
{
   "type": "ORDER_CHECKOUT",
   "channel": "WEB",
   "pos": "myretailsite/ireland",
   "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
   "language": "EN",
   "currency": "EUR",
   "page":"checkout page",
   "order": {
      "referenceId": "123456",
      "orderedAt": "2023-08-23T16:17:16.000Z",
      "status": "PURCHASED",
      "currencyCode": "EUR",
      "price": 200,
      "paymentType": "Card",
      "cardType": "Visa",
      "extensions": [ 
         {
            "name": "ext",
            "key": "default",
            "refundable": true
         }
      ],
      "orderItems": [
         {
            "type": "MOBILE_PHONE",
            "referenceId": "REF-123",
            "orderedAt": "2023-08-23T16:17:16.000Z",
            "status": "PURCHASED",
            "currencyCode": "EUR",
            "price": 200,
            "name": "Mobile phone of type x",
            "productId": "MOBILE_PHONE_TYPE_X",
            "quantity": 1,
            "extensions": [
               {
                  "name": "ext",
                  "key": "default",
                  "phoneColor": "Gold",
                  "insurance": false
               }
            ]
         }
      ]
   }
}

CLEAR_CART event

2.1 data model

You can send a CLEAR_CART event to ensure that Sitecore Personalize ignores any products or contacts that have been passed to Sitecore Personalize during the browser session.

The CLEAR_CART event is typically sent when a guest performs a new search. This removes all products and contacts from the cart and ensures that Sitecore Personalize does not send an abandoned cart email message to the guest.

2.0 data model

You can send a CLEAR_CART event to ensure that Sitecore Personalize ignores any products, consumers, or contacts that have been passed to Sitecore Personalize during the browser session.

The CLEAR_CART event is typically sent when a guest performs a new search. This removes all products, consumers, and contacts from the cart and ensures that Sitecore Personalize does not send an abandoned cart email message to the guest.

Example 50. CLEAR_CART event object
{
    "channel": "MOBILE_APP",
    "type": "VIEW",
    "language": "EN",
    "currency": "EUR",
    "page": "search results page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​"
}
{
    "channel": "MOBILE_APP",
    "type": "VIEW",
    "language": "EN",
    "currency": "EUR",
    "page": "search results page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​"
}

Custom event

A custom event is unique to your organization. For example, most retail sites have an ADD event that captures when a guest clicks the add button. However, you might want to capture, for example, how many times a guest adds items to a wish list, and for this, there is no standard event in Sitecore Personalize. To do this, you can send a custom event, for example, ADD_TO_WISHLIST.

You can track how often a custom event is raised by creating a goal for an experiment in Sitecore Personalize. You can also use the raising of the custom event as the basis for declaring a winner in your experiment.

Notice

You send a custom event in the same way that you send a standard event. You must be consistent with the name of the custom event you send and you must not use the name of a standard event.

You can also add a maximum of 50 custom attributes of your choice.

To send a custom event, use the following required attributes:

Attribute

Type

Description

Example

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

  • MOBILE_APP

  • MOBILE_WEB

  • WEB

type

string (uppercase)

The name of the custom event. This is a custom value of your choice. However, you must not set the value to any of the Sitecore Personalize reserved event names.

You must not set the value to any of the Sitecore Personalize reserved event names:

language

string (uppercase ISO 639-1)

The language the user is using your app in.

  • DE

  • EN

  • FR

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

  • EUR

  • GBP

  • USD

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

  • home

  • contact-us.html

pos

string

The name of the point of sale where the interaction with your brand takes place.

  • myretailsite/ireland

  • spinair.com/france

browser_id

string

The browser ID.

a38b230c-11eb-4cf9-8d5d-274e9f344925​

Example 51. Custom event object
{
    "channel": "MOBILE_APP",
    "type": "ADD_TO_WISHLIST",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​"
}
{
    "channel": "MOBILE_APP",
    "type": "ADD_TO_WISHLIST",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​"
}
Example 52. Custom event object with custom attributes

In the type attribute of the event, the custom event name is specified as myretailsite:CLICKED_POPUP. The event contains the custom attributes clickedPopup and timeBetweenPopupAndClick.

{
    "channel": "MOBILE_APP",
    "type": "myretailsite:CLICKED_POPUP",
    "language": "EN",
    "currency": "EUR",
    "page": "home page",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "ext": {
       "clickedPopup": "true",
       "timeBetweenPopupAndClick": "8 seconds"
    }
}

Sending orders

Sitecore Personalize provides different options for sending orders to Sitecore Personalize. The available options depend on, for example, the frequency of order submission, and whether orders are submitted in real-time, offline, or synchronously.

Sending orders using a single event

You can use Sitecore Personalize to submit orders in real time to Sitecore Personalize. Use this option to submit orders using a single event if your organization's site is tagged to send all order-related data from the confirmation page. You can also use this option if your organization uses an order management system (OMS), or if your organization uses cookies and local storage to capture order details.

2.1 data model

To submit an order to Sitecore Personalize in real time, you must send an ORDER_CHECKOUT event.

2.0 data model

Sending orders using multiple events

You can use Sitecore Personalize to assemble orders in real-time if the booking flow for your organization's site does not facilitate sending all order-related data from the confirmation page. For example, your site's confirmation page might not be tagged to capture and send contact information so you would need to send the ADD_CONTACTS event from a different web page.

2.1 data model

To submit an order to Sitecore Personalize in real time, you must send the following events in this sequence:

2.0 data model

To submit an order to Sitecore Personalize in real time, you must send the following events in this sequence:

Cart abandonment

2.1 data model

You can to track items added to an online cart using the ADD event. If items have been added to the cart, and the stream session closes without an order, then the stream session cartType is set to ABANDONED.

Sitecore Personalize enables you to configure an experience to re-engage with the guest and recover the contents of the abandoned cart, for example, to send the guest an email message with the cart contents. The guest must be identified in order for this to work.

The following steps result in an abandoned cart, which triggers an abandoned cart email message:

  1. A guest adds an item to their cart.

    An ADD event is sent to Sitecore Personalize.

  2. The guest's session closes manually, by timing out, or by network latency.

    Sitecore Personalize sets the stream session cartType to ABANDONED.

  3. If configured, Sitecore Personalize sends a triggered experience.

The following steps result in a CLEAR_CART event being sent to Sitecore Personalize:

  1. A guest adds an item to their cart.

    An ADD event is sent to Sitecore Personalize.

  2. The guest removes the item or items from their cart.

    A CLEAR_CART event is sent to Sitecore Personalize.

  3. The guest's session closes manually, by timing out, or by network latency.

    Sitecore Personalize sets the stream session cartType to CLOSED.

    Sitecore Personalize does not send the triggered experience.

2.0 data model

Send additional event data

Example 53. VIEW event data including the ext object
{
  "type": "VIEW",
  "channel": "WEB",
  "pos": "myretailsite/ireland",
  "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
  "language": "EN",
  "currency": "EUR",
  "page": "home page",
  "ext": {
    "tileRef": 17
  }
}
Example 54. Conflict when sending a VIEW event

The two examples describe a conflict when sending a VIEW event. The conflict occurs because the same attribute name (status) contains an integer value in the first example, but a string value in the second example.

{
   "type":"VIEW",
   "ext":{
      "status": 0
   }
}
{
   "type":"VIEW",
   "ext":{
      "status": "OK"
   }
}

Troubleshooting

401 Unauthorized when trying to get the browser ID

When trying to retrieve the browser ID, this error occurs when the value for the stream_api_target_endpoint parameter or the value for the client_key parameter is incorrect in the URL.

To fix the error:

  1. For the stream_api_target_endpoint parameter, specify the correct Stream API target endpoint.

  2. For the client_key parameter, specify the correct client key.

400 Bad Request error when trying to send an event

This error occurs when the event object does not contain a browser_id or a type.

To fix the error:

  1. In the HTTP request, in the message query parameter, locate the key-value pairs that describe the event.

  2. For the browser_id key, specify the browser ID that you previously retrieved.

  3. Make sure the event object contains a type.

404 Not Found error when trying to send an event

This error occurs when the event object contains the incorrect browser ID.

To fix the error:

  1. In the HTTP request, in the message query parameter, locate the key-value pairs that describe the event.

  2. For the browser_id key, specify the browser ID that you previously retrieved.

Events not appearing in Sitecore Personalize

If you sent an event to Sitecore Personalize and the HTTP response has the 201 Created status code, this issue occurs if the value for the pos key is incorrect.

To fix the error:

  1. In the HTTP request, in the message query parameter, locate the key-value pairs that describe the event.

  2. For the pos key, specify the correct name of a point of sale.

Personalize API Flow execution

You can use the Personalize REST API flow execution service to run a flow for an experiment or experience. You can do this over any web-based or mobile application, so you can personalize dynamic offers or content in real-time. For example, you can nudge the guest onto the next page or encourage them to add a product to their cart or order.

Characteristics of the flow execution service:

  • Facilitates personalization in experiences and experiments, including interactive and web

  • Invokes real-time responses

  • Supports using decision models in interactive experiments to return the next best offer or action

You can send a flow execution request using either the browserIdemail, or identifiers attribute. This flexibility is particularly useful when interacting with guests who have never been identified online and do not have a browserId attribute. You can use the email or identifiers attribute to execute a flow that uses a decision model to return the next best offer or action.

You can also send a flow execution request for an experiment or experience when you want to send the output of the decision model in real-time to an external system such as a marketing cloud. The browserId attribute is not relevant or captured by this type of external system, so we recommend using the email or identifiers attribute to execute the flow.

The following table describes flow execution model attributes:

Attribute

Type

Description

Example(s)

clientKey

string

The client key retrieved from Sitecore Personalize.

"mhbWwbHYfhpheu86hp60oR76S4jQMmZr"

channel

string (uppercase)

The channel captured on each page the guest visited.

"WEB", "MOBILE_WEB", "MOBILE_APP"

language

string (2 letter ISO 639 language code)

The language captured on each page the guest visited.

"EN", "FR", "DE"

currencyCode

3 letter ISO 4217

Your organization’s currency code.

"EUR", "USD", "NZD"

pointOfSale

string (predefined by your organization)

The point of sale used.

"myretailsite.com", "retailsite.co.uk"

browserId

string

The ID of a browser generated by Sitecore Personalize.

"56860bff-94ba-4d84-aa37-2b5a83d5411b"

email

string

The guest's email address.

"john.doe@gmail.com"

identifiers

JSON object

The unique identifiers of the guest.

N/A

params

JSON object

The parameters returned from the visitor's current URL.

N/A

The following table describes identifiers object attributes:

Attribute

Description

Type

Example(s)

provider

The identifier provider.

string

"ProfileSystem"

id

The identifier identification.

string

"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41"

The following table describes params object attributes:

Attribute

Description

Type

Example(s)

utm.campaign

The UTM campaign parameter included in the visitor's current URL.

string

"content_promotion"

utm.source

The UTM source included in the visitor's current URL.

string

"bing"

utm.medium

The UTM medium included in the visitor's current URL.

string

"social"

utm.content

The UTM content included in the visitor's current URL.

string

"call_to_action"

The friendlyID

You can programmatically run experiments and experiences using the friendlyID attribute. When you create an experiment or experience, Sitecore Personalize automatically creates an ID when you name the experiment or experience. For example, if you name an experiment Product Recommender, Sitecore Personalize automatically generates an ID named product_recommender.

In some organizations there might be several variations of an experiment named Product Recommender that have different page targets, audience filters, or other conditions that must be met in order for the experiment to run.

To use this same example, users might intentionally delete some of the experiments named Product Recommender after the marketing campaign is retired. This can often happen across regions. To support referential integrity, Sitecore Personalize automatically appends a numeral to the value of the friendlyID attribute if the name of the experiment you create is identical to any names of deleted experiments. For example, Sitecore Personalize automatically appends a numeral 2 so the friendlyID attribute value is product_recommender_2.

To apply fuzzy matching so that Sitecore Personalize executes the first lexicographical match of the friendlyId, you pass in product_recommender* as the value for the friendlyID attribute. You can use an asterix to apply lexicographical order and execute the first live experment that matches and passes any other conditions such as page targeting and real-time audience filters.

Call the Personalize API

POST /v2/callFlows

Runs an interactive experiment or web experiment over any web-based or mobile application.

You must include one of the following attributes: browserId or email or identifiers. Optionally, you can include custom fields using the params object.

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
   "clientKey":"abBah8aelipaPeebae7roox2tiexoSee",
   "channel":"WEB",
   "language":"en",
   "currencyCode":"EUR",
   "pointOfSale":"retailsite.com",
   "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
   "params":{
      "utm":{
         "campaign":"summer_sale",
         "source":"newsletter",
         "medium":"email",
         "content":"running shoes"
      },
      "friendlyId":"home_page_banner"
   }
}

Run an experiment or experience using browserId:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
    "clientKey": "abBah8aelipaPeebae7roox2tiexoSee",
    "channel": "WEB",
    "language": "en",
    "currencyCode": "EUR",
    "pointOfSale": "myretailsite/ireland",
    "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "friendlyId": "home_page_banner"
}'

Run an experiment or experience using email:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
    "clientKey": "abBah8aelipaPeebae7roox2tiexoSee",
    "channel": "WEB",
    "language": "en",
    "currencyCode": "EUR",
    "pointOfSale": "myretailsite/ireland",
    "email": "jane.doe@myretailsite.com",
    "friendlyId": "home_page_banner"
}'

Run an experiment or experience using identifiers:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
    "clientKey": "abBah8aelipaPeebae7roox2tiexoSee",
    "channel": "WEB",
    "language": "en",
    "currencyCode": "EUR",
    "pointOfSale": "myretailsite/ireland",
    "identifiers":{
      "id":"123456",
      "provider":"BXLP"
    },
    "friendlyId": "home_page_banner"
}'

Include custom fields:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
    "clientKey": "abBah8aelipaPeebae7roox2tiexoSee",
    "channel": "WEB",
    "language": "en",
    "currencyCode": "EUR",
    "pointOfSale": "retailsite.com",
    "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "params":{
      "loggedInState":"loggedIn",
      "someKey":"someValue"
    },
    "friendlyId": "home_page_banner"
}'

Include UTM parameters in the params.utm object:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
   "clientKey":"abBah8aelipaPeebae7roox2tiexoSee",
   "channel":"WEB",
   "language":"en",
   "currencyCode":"EUR",
   "pointOfSale":"retailsite.com",
   "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
   "params":{
      "utm":{
         "campaign":"summer_sale",
         "source":"newsletter",
         "medium":"email",
         "content":"running shoes"
      },
      "friendlyId":"home_page_banner"
   }
}

Run an experiment or experience using browserID:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
    "clientKey": "abBah8aelipaPeebae7roox2tiexoSee",
    "channel": "WEB",
    "language": "en",
    "currencyCode": "EUR",
    "pointOfSale": "myretailsite/ireland",
    "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "friendlyId": "home_page_banner"
}'

Run an experiment or experience using email:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
    "clientKey": "abBah8aelipaPeebae7roox2tiexoSee",
    "channel": "WEB",
    "language": "en",
    "currencyCode": "EUR",
    "pointOfSale": "myretailsite/ireland",
    "email": "jane.doe@myretailsite.com",
    "friendlyId": "home_page_banner"
}'

Run an experiment or experience using identifiers:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
    "clientKey": "abBah8aelipaPeebae7roox2tiexoSee",
    "channel": "WEB",
    "language": "en",
    "currencyCode": "EUR",
    "pointOfSale": "myretailsite/ireland",
    "identifiers":{
      "id":"123456",
      "provider":"BXLP"
    },
    "friendlyId": "home_page_banner"
}'

Include custom fields:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
    "clientKey": "abBah8aelipaPeebae7roox2tiexoSee",
    "channel": "WEB",
    "language": "en",
    "currencyCode": "EUR",
    "pointOfSale": "retailsite.com",
    "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "params":{
      "loggedInState":"loggedIn",
      "someKey":"someValue"
    },
    "friendlyId": "home_page_banner"
}'

Include UTM parameters in the params.utm object:

Request
curl -X POST '<baseURL>/v2/callFlows' \
-H 'Accept: application/json' \
--data-raw '
{
   "clientKey":"abBah8aelipaPeebae7roox2tiexoSee",
   "channel":"WEB",
   "language":"en",
   "currencyCode":"EUR",
   "pointOfSale":"retailsite.com",
   "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
   "params":{
      "utm":{
         "campaign":"summer_sale",
         "source":"newsletter",
         "medium":"email",
         "content":"running shoes"
      },
      "friendlyId":"home_page_banner"
   }
}
Response
json
[
    {
    "trackingUrl": "<apiEndpoint>/v3/trackers/eyJjaGFubmVsIj",
      "Name": "Ancillary bundle",
      "imageURLForTesting": "https://png.icons8.com/ios/50/000000/cardboard-box.png"
    },
    {
    "trackingUrl": "<apiEndpoint>/v3/trackers/eyJjaGFubmVsIj",
      "Name": "Ancillary seat",
      "imageURLForTesting": "https://png.icons8.com/dotty/50/000000/flight-seat.png"
    },
    {
    "trackingUrl": "<apiEndpoint>/v3/trackers/eyJjaGFubmVsIj",
      "Name": "Ancillary bag",
      "imageURLForTesting": "https://png.icons8.com/metro/50/000000/suitcase.png",
      "nonDependent": "false"
    },
    {
    "trackingUrl": "<apiEndpoint>/v3/trackers/eyJjaGFubmVsIj",
      "Name": "Ancillary insurance",
      "imageURLForTesting": "https://png.icons8.com/ios/50/000000/umbrella.png",
      "nonDependent": "false"
    }
]