Sitecore CDP developer documentation

Welcome to the new Sitecore CDP developer documentation

Provides an introduction to the Sitecore CDP developer documentation.

We updated the Sitecore CDP 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.

  • 2.1 developer documentation and 2.0 developer documentation is no longer published on separate developer sites. We introduced a data model switcher that enables users to toggle to 2.0 code samples and attribute tables, if required. The 2.1 data model code samples and attribute tables display as the default.

    Data model switcher
  • Introduced a tripane layout, enabling you to copy code examples from the right pane.

  • All the articles are now on a single page, allowing you to search all the content using your web browser's search tools.

  • 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 CDP APIs.

February 2023

The new Sitecore Engage SDK is a modern, easy-to-use tool that helps you integrate your application with Sitecore CDP. The updated Integrating with Sitecore CDP section describes how to use the Engage SDK.

Overview

Sitecore Customer Data Platform (CDP) lets you collect, connect, and activate customer data 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 CDP.

  • The Batch API lets you upload large amounts of guest data and offline orders in an efficient manner to Sitecore CDP.

  • The REST APIs let you to retrieve, create, update, and delete data that is available in Sitecore CDP.

  • The data lake export service lets you access, export, and transfer all your organization's data from Amazon Simple Storage Service (Amazon S3) to another Amazon S3 bucket or to your organization's own premises.

Data capturing.

Data models

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

If your organization purchased Sitecore CDP after March 2021, your instance of Sitecore CDP 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 CDP 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 CDP, 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.

Sitecore APIs are flexible by-design. To ensure that the data is viewable in the guest profile and can be used in batch segmentation, 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 guest data

Sitecore CDP enables you to manage guest data using the following APIs:

  • Batch API - Use to create, update, and delete guest profiles in Sitecore CDP. This API is commonly used to upload large amounts of guest data in an efficient manner when integrating Sitecore CDP with your application. For example, you might decide to load the last 12 months of customer data from your legacy system before going live with Sitecore CDP. To ensure that you can view the data in guest profiles and access it in batch segmentation, you must model the guest data object for the Batch API.

    The Sitecore CDP Batch API enables you to use a guest data extension to send additional guest data to Sitecore CDP that isn't part of the guest data model. This enables your organization to capture additional information about the guest in their guest profile and use that data in batch segmentation. To do this, you must model the guest extension data object for the Batch API.

  • Stream API - Use to capture guest, behavioral, and order data in real-time, as the guest navigates your application.

    Sitecore CDP provides events that you can use to capture guest data, whether it's related to order information or tracking data, it's all captured and visible in the guest profile. Your organization can send additional, custom data with an event and use that data in real-time personalization, decisioning, and batch segmentation, just like you can with other event data.

  • REST API - Use to create and update guest profiles in Sitecore CDP. To ensure that you can view the data in guest profiles and access it in batch segmentation, you must model the guest data object for the REST API.

    The Sitecore CDP REST API enables you to use a guest data extension to send additional guest data to Sitecore CDP that isn't part of the guest data model. This enables your organization to capture additional information about the guest in their guest profile and use that data in batch segmentation. To do this, you must model the guest extension data object for the REST API.

Sending events

Use the Stream API to collect and send behavioral data to Sitecore CDP 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 view use that data in batch segmentation. It is also available to view in the guest profile.

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 CDP provides different APIs for sending orders to Sitecore CDP. 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 view the order data in guest profiles and use order data in batch segmentation. 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 CDP.

Managing orders in real-time

Use the Stream API to collect and send order data in real-time to Sitecore CDP, 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.

All order and order item information is captured and is visible in the guest profile.

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 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 CDP.

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

You can not update or delete an order using Stream API. To do this, use the Batch API or REST API.

Managing orders synchronously

Use the REST API to synchronously create and update orders and order items in Sitecore CDP.

To ensure the order data is available in the UI, you must follow the guidelines for the order data model and order item data model for REST API.

Offline order submission

Use the Batch API to create, update and delete offline orders. You can use offline order submission with the Batch API to do any of the following:

  • Submit a large amount of historical orders from a data lake or data warehouse as a once-off, when your organization first integrates with Sitecore CDP.

  • Submit offline orders from a third-party system, such as a call center.

  • Submit orders for guests who block cookies or who use an anonymous browser.

  • Submit complete orders if your organization submits partial orders using Stream API.

  • Update orders submitted with Stream API on a daily basis.

You can use an order data extension to send additional order data to Sitecore CDP that isn't part of the order data model. An order data extension is an array that enables you to specify whatever name/value pairs (attributes) your organization wants. This lets your organization capture additional information about the order, view it in their guest profile, and use that data in batch segmentation, just like you can with other order data.

You can also use an order item data extension to send additional order item data to Sitecore CDP that isn't part of the order item data model. An order item data extension has the same traits as an order data extension.

To ensure the order data is available in the UI, you must follow the guidelines for the order data model, order extension data model, order item data model, and order item extension data model for the Batch API.

Stream API

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

We recommend that you integrate using the Sitecore Engage SDK.

Overview

Sitecore CDP 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 SDK, the Engage SDK uses 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 CDP 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 CDP 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 CDP 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 CDP

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

We recommend that you integrate using the Sitecore Engage SDK.

During integration

During integration, you start collecting and sending real-time behavioral and transactional data to Sitecore CDP 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 CDP starts capturing the behavioral and transactional data from your app. You can then act on that data by:

  • Building segments of your customers using the data you have collected.

  • Activating your audiences in external systems.

  • Viewing your data in pre-built analytic dashboards.

Preparing to integrate

Before you integrate with Sitecore CDP, you have to:

  • Collect required details about your Sitecore CDP instance.

  • Choose an integration type.

Collect required details

During integration, you have to provide details about your Sitecore CDP 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 CDP instance.

To find the environment, in Sitecore CDP, 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 CDP, 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 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 CDP 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)

If you have Sitecore Personalize, decide whether you want to run personalization with Sitecore Personalize. This affects how you initialize the Engage SDK.

Choose an integration type

Sitecore CDP offers various integration options. We recommend that you integrate using the Sitecore Engage SDK in one of the following ways:

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

Integration

Characteristics

Client-side integration using the Engage SDK script and a TMS

  • Quick and easy to integrate into existing websites using a browser script.

  • No website deployment needed.

  • The TMS can control when to load the script.

  • Supports client-side tracking.

  • The Engage SDK automatically collects geolocation data.

Client-side integration using the Engage SDK script

Integration using the Engage SDK package

  • 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 SDK script 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, see how to upgrade to the Engage SDK.

Walkthrough: Integrating using the Engage SDK script and Google Tag Manager

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

This walkthrough assumes that you:

This walkthrough describes how to:

  • Add a tag for the Engage SDK to your website.

  • Verify that the script loads on your website.

  • Add more tags to your website.

Add a tag for the Engage SDK 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 SDK script and fires when the DOM is ready. The script initializes the Engage SDK 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 SDK.

  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 SDK 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 SDK
        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 CDP 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 SDK.

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

Verify that the script 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 Engage SDK fires on your website.

To verify that the Engage SDK script 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 script on your website and sent a VIEW event.

Add more tags to your website

The Engage SDK 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 CDP. You sent an event from your website, and Sitecore CDP now captures data about your users in real time.

Walkthrough: Integrating using the Engage SDK script

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

This walkthrough assumes that you:

  • Have collected the required details about your Sitecore CDP 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 script on your website.

  • Verify that the script loads on your website.

  • Send your first VIEW event.

  • Verify that Sitecore CDP captured your VIEW event.

Load the script on your website

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

To load the script:

  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.js

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

    // Initialize the engage variable
    var engage = undefined;
    
    // Create and inject the <script> tag into the HTML
    var s = document.createElement("script");
    s.type = "text/javascript";
    s.async = true;
    s.src = "https://d1mj578wat5n4o.cloudfront.net/sitecore-engage-v.1.3.0.min.js";
    var x = document.querySelector("script");
    x.parentNode.insertBefore(s, x);    
    
    // Initialize the Engage SDK
    s.addEventListener("load", async () => {
        var settings = {
            clientKey: "<client_key_PLACEHOLDER>",
            targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
            pointOfSale: "<point_of_sale_PLACEHOLDER>",
            cookieDomain: "<cookie_domain_PLACEHOLDER>",
            cookieExpiryDays: 365,
            forceServerCookieMode: false,
            includeUTMParameters: true,
            webPersonalization: "<boolean_or_object>"
        };
        engage = await window.Engage.init(settings);
        
        // Send a VIEW event
        // ...
    });

    Replace the placeholder values with the required details from your Sitecore CDP 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 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.js"></script>
        <script></script>
        <script></script>     
      </body>
    </html>

Verify that the script loads on your website

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

  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 script on your website.

Send your first VIEW event

After you have verified that the script loads on your website, you collect and send data to Sitecore CDP. 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 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 CDP > Guests > Search field:");
    console.log("bid:", engage.getBrowserId());

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

    This script creates a VIEW event object and sends the event data to Sitecore CDP 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 CDP.

  3. In your web browser, reload the webpage. The VIEW event triggers and the event data is sent.

Verify that Sitecore CDP captured your VIEW event

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

To verify that Sitecore CDP 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 CDP, 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 CDP, click Guests. Paste the copied text into the Search field.

    An anonymous guest displays.

    Search field in the Guests screen.

    This guest is you loading your app just a minute ago. Next, you find the VIEW event associated with this guest.

  4. Click the guest. The guest profile displays.

  5. On the guest profile page, click Event viewer. A list of events associated with this guest displays. The list contains a VIEW event. This is the event that was triggered in the previous procedure.

Next steps

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

Walkthrough: Integrating a React app using the Engage SDK package

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

This walkthrough assumes that you:

This walkthrough describes how to:

  • Install and initialize @sitecore/engage.

  • Send your first VIEW event.

  • Verify that Sitecore CDP 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 CDP instance.

    This script:

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

    • Asynchronously loads the Engage API using details about your Sitecore CDP 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 CDP. 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 CDP > Guests > Search field:");
          console.log("bid:", engage.getBrowserId());
        };
      };
    
      return <></>;
    }
    

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

    This script creates a VIEW event object and sends the event data to Sitecore CDP 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 CDP.

  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 CDP captured your VIEW event

Next steps

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

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

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

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 CDP 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 CDP instance.

    This script:

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

    • Asynchronously loads the Engage API using details about your Sitecore CDP 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 CDP. 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 CDP > Guests > Search field:");
          console.log("bid:", engage.getBrowserId());
        };
      };
    }
    

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

    This script creates a VIEW event object and sends the event data to Sitecore CDP 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 CDP.

  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 CDP captured your VIEW event

Next steps

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

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

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

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 CDP 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 CDP instance.

    This script:

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

    • Collects the details about your Sitecore CDP 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 CDP 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 CDP. 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 CDP > Guests > Search field:");
      console.log("bid:", engage.getBrowserId());
    };
    

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

  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 CDP captured your VIEW event

Next steps

You've now successfully integrated your app with Sitecore CDP. You sent an event from your app and verified that Sitecore CDP 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 CDP 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 CDP.

  • Send your first VIEW event.

  • Verify that Sitecore CDP captured your VIEW event.

Get the browser ID from Sitecore CDP

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

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 CDP 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 CDP.

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 CDP 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 CDP 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 CDP.

Verify that Sitecore CDP captured your VIEW event

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

To verify that Sitecore CDP captured your VIEW event:

  1. In Sitecore CDP, click Guests. In the Search field, enter the bid: prefix plus the browser ID that you retrieved in a previous step.

    Example search string:

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

    Tip

    In Sitecore CDP, 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​

    An anonymous guest displays.

    Search field in the Guests screen.

    This is you making an HTTP request to get the browser ID in a previous step. Next, you find the VIEW event associated with this guest.

  2. Click the guest. The guest profile displays.

  3. On the guest profile page, click Event viewer. A list of events associated with this guest displays. The list contains a VIEW event. This is the event that was triggered in the previous procedure.

Next steps

You've now now successfully integrated your app with Sitecore CDP. You made an HTTP request to get the browser ID. Then, using the browser ID, you sent a VIEW event and verified that Sitecore CDP captures data about your users in real time.

Next, you can:

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

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

This walkthrough assumes that you:

  • Have an app that uses the Boxever JavaScript Library.

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

This walkthrough describes how to:

  • Update the initializing script.

  • Update the VIEW event script.

  • Update the scripts for sending other events.

  • Update the script for running personalization.

Update the initializing script

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

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

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

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

Note the following details about the Engage SDK script:

  • The engage variable is initialized as undefined.

  • After the <script> tag loads, the asynchronous init() function loads the Engage SDK on your webpages. The engage variable is reassigned to the return value of the init() function.

  • The settings object has different attributes than _boxever_settings in the Boxever JavaScript Library. For example, client_key is now clientKey and target is now targetURL.

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

Update the VIEW event script

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

Your existing script using the Boxever JavaScript Library:

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

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

Note the following details about the Engage SDK script:

  • The event object has different attributes than in the Boxever JavaScript Library. browser_id and type are no longer part of the event object. pos is now pointOfSale.

  • The VIEW event has a dedicated function called Engage.pageView().

Update the scripts for sending other events

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

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

Event type

Function

VIEW

Engage.pageView()

IDENTITY

Engage.identity()

  • ORDER_CHECKOUT

  • ADD

  • CONFIRM

  • CHECKOUT

  • PAYMENT

  • CLEAR_CART

  • SEARCH

  • custom event

Engage.event()

Next steps

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

Next, you can:

Understanding integration details

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

Browser ID

The browser ID is a universally unique identifier (UUID) that Sitecore CDP 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 SDK

The Engage SDK automatically creates 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 CDP.

When you send events, the Engage SDK automatically includes the browser ID in the event 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 CDP, you have to manually include the browser ID.

The browser ID in Sitecore CDP

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 CDP.

Then, Sitecore CDP 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 SDK automatically collects 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

Sitecore CDP 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 package, 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 SDK

Using the Engage SDK, you can collect and send behavioral data to Sitecore CDP 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 CDP using either client-side tracking or server-side tracking. Using the Engage SDK script, you can implement client-side tracking. Using the Engage SDK package, you can implement 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 SDK

Using the Engage SDK, you can collect and send transactional data to Sitecore CDP 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. Using the Engage SDK script, you can implement client-side tracking. Using the Engage SDK package, you can implement 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 CDP 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 CDP 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 CDP 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 CDP.

Server-side tracking with the Engage SDK package

If you can access the server side of your app, you can use the Engage SDK package 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 CDP.

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 CDP.

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 CDP.

  • 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 package, 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 SDK

Using 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 CDP

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

Running personalization

Running web experiences and web experiments

While you're initializing 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 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 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 SDK script, you can call, for example, the Engage.pageView() function inside your web experience or web experiment.

If you integrate using the Engage SDK package, 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 initialize the Engage SDK on your website, you can check which version of Sitecore Engage your website is using.

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 other 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 the sitecore-engage-v. string. 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.

Sitecore Engage SDK reference

Sitecore Engage is a JavaScript SDK that lets you integrate your app with Sitecore CDP.

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

Functions

Use this reference for creating your Engage SDK functions.

Engage.init(settings)

The asynchronous init() function initializes 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 CDP instance and cookie settings.

Example 1. Example: Engage SDK script

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 SDK
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 SDK
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 package

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 CDP 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 CDP.

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 CDP.

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 CDP
        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 CDP
        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 CDP reserved event names, for example, VIEW, ADD, or CONFIRM, the event becomes a standard event.

Sitecore CDP 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 CDP 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();
  };
};

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 CDP reserved event names, for example, VIEW, ADD, or CONFIRM, the event becomes a standard event.

Sitecore CDP 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 CDP 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;
};

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 CDP.

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 CDP.

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 CDP 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 CDP, 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 CDP. 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 in the guest profile.

When you build this object, use a flat object structure. Sitecore CDP 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);
};

Settings object

Use the settings object to initialize the Engage SDK. In the settings object, you include details about your Sitecore CDP 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 CDP 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 CDP.

If you don't specify pointOfSale in the settings object, you must specify it in every event 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 SDK.

Errors in the console

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, 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-0009

pointOfSale cannot be empty.

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

Events not appearing in Sitecore CDP

This issue occurs if you sent an event to Sitecore CDP 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 CDP

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 release notes for the Sitecore Engage SDK.

Version

Release notes

1.3.0

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

1.2.0

Improvements to running personalization. Only applicable if you have Sitecore Personalize.

1.1.0

The Engage SDK now supports server-side tracking.

1.0.0

Adds the ability to:

Boxever JavaScript Library (legacy)

Important

The Boxever JavaScript Library is no longer receiving updates.

We recommend that you upgrade to the Sitecore Engage SDK to get future updates and enhancements.

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 CDP. An event is all the data about a user's interaction with your application. Call this function as part of the anonymous function that you add to the _boxeverq array.

Parameters

Parameter

Type

Description

Note

event

object

All the event data.

Specify the browser ID in this object.

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

callback

function

This callback function handles the response.

N/A

format

string

The format of the response.

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

Return value

undefined

Example

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

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 CDP 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 CDP 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 CDP.

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

Parameters

Parameter

Type

Description

Note

browserId

string

The browser ID.

Set the value to Boxever.browser_id.

clientKey

string

The client key.

Set the value to Boxever.client_key.

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

callback

function

This callback function handles the response.

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

format

string

The format of the response.

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

Return value

undefined

Example

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

Boxever.getBucketNumber([callback])

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

Note

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

Parameters

Parameter

Type

Description

Note

[callback]

optional

function

This callback function handles the response.

N/A

Return value

undefined

Example

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

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

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

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

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

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 CDP must include the browser ID.

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

Parameters

none

Return value

string

Example

Log the browser ID to the console:

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.

We recommend that you upgrade to the Sitecore Engage SDK to get future updates and enhancements.

If you integrate with Sitecore CDP 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 CDP.

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 CDP standard event, for example, VIEW or IDENTITY, set the value to a Sitecore CDP 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 CDP.

Sitecore CDP 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 CDP.

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 CDP, 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 CDP 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 CDP. 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 Sitecore Engage SDK to get future updates and enhancements.

If you integrate with Sitecore CDP 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 CDP, and Sitecore CDP 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 CDP.

  • 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 CDP, 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 CDP

If you sent an event to Sitecore CDP 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 CDP 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 CDP instance.

To find the environment, in Sitecore CDP, 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 CDP client key as a query string parameter in the URI of the request.

Example 27. 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 CDP 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 CDP.

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 SDK. Using 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 CDP 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 CDP standard event, for example, VIEW or IDENTITY, set the value to a Sitecore CDP 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 CDP reserved event names.

Sitecore CDP 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 CDP.

myretailsite/ireland

browser_id

string

The browser ID.

The browser ID is a string similar to:

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

Example 28. 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 29. 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 30. 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 31. 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 32. 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 33. 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 34. 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 35. 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 CDP when the search results page loads.

Example 36. 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 37. 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 38. 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 39. 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 CDP.

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 40. 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 41. 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 42. 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 43. 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 44. 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 CDP.

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 CDP.

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 45. 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 46. 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 CDP ignores any products or contacts that have been passed to Sitecore CDP 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 CDP 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 CDP ignores any products, consumers, or contacts that have been passed to Sitecore CDP 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 CDP does not send an abandoned cart email message to the guest.

Example 47. 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 CDP. 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 CDP reserved event names.

You must not set the value to any of the Sitecore CDP 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 48. 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 49. 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 CDP provides different options for sending orders to Sitecore CDP. 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 CDP to submit orders in real time to Sitecore CDP. 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 CDP in real time, you must send an ORDER_CHECKOUT event.

2.0 data model

Sending orders using multiple events

You can use Sitecore CDP 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 CDP in real time, you must send the following events in this sequence:

2.0 data model

To submit an order to Sitecore CDP in real time, you must send the following events in this sequence:

Managing orders synchronously

You can manage orders synchronously using the REST API to do any of the following:

  • Create, locate, retrieve, update and delete orders and order items

  • Update orders that have the same referenceId values and have orderedAt values (purchase dates) within two days of another.

  • Send additional data with orders using order data extensions

  • Send additional data with order items using order item data extensions

Offline order submission

Note

Offline order submission is performed using the Batch API.

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 CDP.

  2. The guest's session closes manually, by timing out, or by network latency.

    Sitecore CDP 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 CDP:

  1. A guest adds an item to their cart.

    An ADD event is sent to Sitecore CDP.

  2. The guest removes the item or items from their cart.

    A CLEAR_CART event is sent to Sitecore CDP.

  3. The guest's session closes manually, by timing out, or by network latency.

    Sitecore CDP sets the stream session cartType to CLOSED.

    Sitecore Personalize does not send the triggered experience.

2.0 data model

Send additional event data

Example 50. 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 51. 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 CDP

If you sent an event to Sitecore CDP 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.

Batch API

The Batch API lets you efficiently upload large amounts of data to Sitecore CDP.

Overview

You can use the Batch API to upload guests, orders, and tracking events, which organizations can source in bulk from their internal systems before sending to Sitecore CDP for processing.

Data capturing.

Using the Batch API involves uploading one or more batch files into Sitecore CDP. Before you upload a batch file, you must ensure that the file meets formatting requirements.

The Batch API supports asynchronous requests: you can initiate multiple batch imports in parallel. After a batch file has been submitted for processing, users can periodically check on the progress of the batch import, until the batch has been completely processed. You can interrogate the Batch API at any time to check the status of a batch that is being processed, and to view any success or failure messages which might be logged after the processed batch is complete.

When to use the Batch API

Integration Engineers can use the Batch API to import large amounts of offline data in order to support:

  • Greater flexibility in guest segmentation.

  • A more comprehensive single customer view.

  • Higher sophistication of decision logic.

Base URL

The base URL is determined by the environment of your Sitecore CDP instance.

To find the environment, in Sitecore CDP, 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

The Sitecore CDP Batch API uses basic authentication.

Basic authentication involves sending a user name and a password with every request. To find your user name and password, in Sitecore CDP, on the navigation pane, click cdp_gear_icon.png > API access:

  • The user name is the Client Key.

  • The password is the API Token.

Example 52. Sending a user name and a password with a request
curl -X GET '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \
-u '<username>:<password>' \
-H 'Accept: application/json'
curl -X GET '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \
-u '<username>:<password>' \
-H 'Accept: application/json'

Batch file formatting requirements

The Batch API supports uploading gzipped archive files (.gz). The gzipped file must contain at least one JSON file. For example, if the data you want to upload is in import.json, you must gzip the JSON file and upload import.json.gz.

JSON records in the JSON file

Every JSON file must contain a separate JSON record for each entity to import. Each JSON record must be:

  • Valid JSON.

  • Minified, contained on a single line.

  • Terminated with a carriage return.

  • Encoded according to RFC 4627.

Note

Including multiple JSON records in the JSON file will make the file invalid, which is normal. The important part is that each JSON record must be valid JSON.

Each JSON record must include the following required fields:

Field name

Type

Description

ref

string

Version 3 or 5 UUID

A unique ID that identifies the JSON record during the upload process. This ID is not used inside Sitecore CDP to identify the guest or the record; it is for the upload process only.

schema

string

Must be one of:

  • guest

  • order

  • tracking

  • migration

The type of record contained in the value field that is being imported. Only use "migration" as the value for "schema" when migrating guests. See Guest migration data model.

mode

string

Must be one of:

  • insert

  • upsert

  • guest

Indicates how to import the record into the system:

insert - overwrites everything belonging to the existing entity resulting in a new one being created

upsert - updates the existing entity only with the fields set in the request. If the entity does not exist, a new one is created.

guest - applies specific migration rules to how the fields are updated. Only use "guest" as the value for "mode" when migrating guests. See Guest migration data model.

value

JSON object

Contains the entity to be imported into Sitecore CDP.

Not all fields for each object are required to be present during the upload. The exception is for guest data extensions, where depending on the type of guest data extension, all fields might be required.

When using upsert mode for a guest, you only need to include enough data to identify the guest within Sitecore CDP, as well as the fields to be updated.

When using guest mode for a guest, all fields required to deem the entity valid must be included because the update must result in a valid entity.

Example 53. This sample JSON file (import.json) contains two JSON records for two guests: jane.doe@myretailsite.com and john.doe@myretailsite.com. Each record is in a separate row. Each row is valid JSON although the JSON file as a whole is not.
{"ref":"ace73c06-b361-11ed-afa1-0242ac120002","schema":"guest","mode":"upsert","value":{"guestType":"customer","identifiers":[{"provider":"email","id":"jane.doe@myretailsite.com"}],"extensions":[{"name":"ext","key":"default","loyaltyNumber":"1234"}]}}
{"ref":"7e1d404e-9fd5-4df5-acfe-3a64848ec594","schema":"guest","mode":"upsert","value":{"guestType":"customer","identifiers":[{"provider":"email","id":"john.doe@myretailsite.com"}],"extensions":[{"name":"ext","key":"default","loyaltyNumber":"5678"}]}}
{"ref":"ace73c06-b361-11ed-afa1-0242ac120002","schema":"guest","mode":"upsert","value":{"guestType":"customer","identifiers":[{"provider":"email","id":"jane.doe@myretailsite.com"}],"extensions":[{"name":"ext","key":"default","loyaltyNumber":"1234"}]}}
{"ref":"7e1d404e-9fd5-4df5-acfe-3a64848ec594","schema":"guest","mode":"upsert","value":{"guestType":"customer","identifiers":[{"provider":"email","id":"john.doe@myretailsite.com"}],"extensions":[{"name":"ext","key":"default","loyaltyNumber":"5678"}]}}

Walkthrough: Uploading a batch file

In this walkthrough, you upload a batch file to Sitecore CDP.

This walkthrough assumes that you:

This walkthrough describes how to:

  • Gzip your JSON file.

  • Collect required details.

  • Upload the gzipped file.

  • Verify that Sitecore CDP ingested the uploaded data.

Gzip your JSON file

Before you can upload a batch file, you gzip your JSON file and use the gzipped file in the upload process.

To gzip your JSON file:

For example, if the data you want to upload is in import.json, the gzipped file is import.json.gz.

Tip

There is a 50MB size limit for uploading batch files.

If the size of the gzipped file exceeds the 50MB limit, recompress the original JSON files into two or more gzipped files that do not exceed the 50MB size limit. Then, upload the gzipped files as separate batches.

Collect required details

After you have created the gzipped file, you collect required details. You use these details when you start the upload process.

Detail

Type

Description

Example

File size in bytes

integer

The size in bytes of the gzipped file (import.json.gz). You can check this in the file's properties.

3456

MD5 checksum

string

A hex-encoded MD5 checksum for the gzipped file. This is to provide assurance that the integrity of the gzipped file is intact.

40d9a12f0a3c93c8ed66a3b6f3735790

Base64 string

string

The same hex-encoded MD5 checksum, converted to Base64.

hmhSUwGGLymfT1gmfmkCSA==

UUID for batch reference

string

The UUID of a batch upload.

This a UUID that you generate. It must be unique across all batches. You can use online tools to generate a UUID.

3ee694e5-0b77-2d1e-af19-1aa78f500785

Upload the gzipped file

After you have collected the required details, you can start the upload process. In this process, you first allocate a batch upload location, then start uploading the gzipped file, then retrieve the status of the upload.

To upload the gzipped file:

  1. Make a PUT request to allocate a batch upload location.

    curl -X PUT '<baseURL>/v2/batches/<batchRef_UUID>' \
    -u '<username>:<password>' \
    --data-raw '
    {
      "checksum": "<MD5_checksum>",
      "size": <file_size_in_bytes>
    }'
    

    Note that you must:

    • Use basic authentication.

    • Replace <baseURL> with your base URL. Replace <batchRef_UUID>, <MD5_checksum>, and <file_size_in_bytes> with the values you collected in the previous procedure.

    In the response, in the location object, the href key contains the batch upload path. You use the batch upload path in the next step. The batch upload path is valid for 1 hour.

    Example batch upload path:

    https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/...

  2. Make a PUT request to the batch upload path. This request starts the upload.

    curl -X PUT 'https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/...' \
    -H 'x-amz-server-side-encryption: AES256' \
    -H 'Content-Md5: <Base64_string>' \
    --data-binary '<path_to_gzipped_file>'

    Note that you must:

    • Not use basic authentication, contrary to the previous step.

    • Specify the headers as seen in the code sample above. Replace <Base64 string> with the value you collected in the previous procedure.

    • In --data-binary, specify the path to the gzipped file. You must upload a file in the body as binary data.

      Example: @/C:/Users/user/Desktop/import.json.gz

      Tip

      If you are using Postman, click Body > binary > Select File.

    This request returns an empty, 200 OK response.

  3. Make a GET request to retrieve the batch file upload status.

    curl -X GET '<baseURL>/v2/batches/<batchRef_UUID>' \
    -u '<username>:<password>' \
    -H 'Accept: application/json'
    

    Note that you must:

    • Use basic authentication.

    • Replace <baseURL> with your base URL. Replace <batchRef_UUID> with the same batch reference you used when you made a PUT request to allocate a batch upload location.

    In the response, the status object contains information about the upload status. First, the status is processing. After the upload succeeds, the status is success.

Verify that Sitecore CDP ingested the uploaded data

After the upload succeeds, you log in to Sitecore CDP to find the uploaded data. In this example, you search for the guests listed in our sample JSON records.

To verify that Sitecore CDP ingested the uploaded data:

  1. In Sitecore CDP, click Guests. In the Search field, enter the email address of one of the uploaded guest records, for example, jane.doe@myretailsite.com.

    The guest displays.

  2. Click the guest. The guest profile displays.

  3. On the guest profile page, click Properties. The uploaded details about the guest displays. For the guests listed in our sample JSON records, the details include First Seen, Last Seen, and data extensions in the Ext attribute, for example, LoyaltyNumber.

You have now successfully uploaded a batch file to Sitecore CDP. You gzipped your JSON file, started the upload, and verified that Sitecore CDP ingested the uploaded data.

Reference

When you are uploading a batch file to Sitecore CDP, use this reference for making the network requests.

Allocate batch upload location

PUT /v2/batches/batchRef

Creates a location to which you subsequently upload the batch file.

You must provide the following required attributes in the request body:

Attribute

Type

Description

Example

checksum

string

A hex-encoded MD5 checksum for the gzipped file. This is to provide assurance that the integrity of the gzipped file is intact.

40d9a12f0a3c93c8ed66a3b6f3735790

size

integer

The size in bytes of the gzipped file (import.json.gz). You can check this in the file's properties.

3456

In the response, in the location object, the href key contains the batch upload path. You use the batch upload path when you upload the batch file.

The response body contains the following fields:

Attribute

Description

Type

href

Echo back of the URL used in this request.

string

ref

UUID of the batch, forms part of the href.

string

checksum

Echo back of checksum of the uploading file.

string

size

Echo back of the size of the uploading file.

integer

location

Details of the file upload location.

object

location.href

The allocated URL to which you upload the batch file. This URL is valid for one hour.

string

location.expiry

Date and time that the upload location href expires.

date time

status

The status of the file upload.

object

status.code

The batch file processing status. Possible values:

  • uploading - the import process was initialized by the client.

  • processing - import file was uploaded and processing has started.

  • success - import file was successfully processed.

  • corrupted - import file did not match the checksum.

  • error - import has failed, see the log file. The location of the log file is the value of the status.log parameter.

string

createdAt

Date and time the request was created.

date time

modifiedAt

Date and time the request was last updated.

date time

Request
curl -X PUT '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \
-u '<username>:<password>' \
-H 'Accept: application/json' \
--data-raw '
{
  "checksum": "b1d600dbf7463924e24647e626cd7c1e",
  "size": 227
}'
Request
curl -X PUT '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \
-u '<username>:<password>' \
-H 'Accept: application/json' \
{
  "checksum": "b1d600dbf7463924e24647e626cd7c1e",
  "size": 227
}'
Response

location.href contains the batch upload path:

JSON
{
    "href": "<baseURL>/v2/batches/12af3453-62da-4b31-b646-631b7b5f3009",
    "ref": "12af3453-62da-4b31-b646-631b7b5f3009",
    "checksum": "b1d600dbf7463924e24647e626cd7c1e",
    "size": 227,
    "location": {
        "href": "https://sitecore-batch-service-production-eu-west-1.s3.eu-west-1.amazonaws.com/pqsTELpfrXBzxKozB0IoL4xuAT0s7WrH/12af3453-62da-4b31-b646-631b7b5f3009/import.gz?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEDAaCWV1LXdlc3QtMSJIMEYCIQCvLllsVnScVKunabp2ecWZ35wWC2qazGUOH38uZ4ebNwIhAPhKsvrNikvkBSJwFo4Heat72zODcLQCPzh87PRThE8qKtUECIn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMNDkzNDAzOTY5MDY2IgzaKR3yFcEnGvR0NjEqqQQiccx7113xYh5boBVgjPQrzpcCLKgXi563nzp0YRIM52WE1LFEezlLQBEcRl9wo0i5ko5%2F8ne%2BPSFGxkc576fPqkdQzQyX9Ub1PA44pwuFzK%2FZSf9mHS7FRqPvvuxlm7srdkceEJK2VAmoUehfKHzDYhtCkPnZyElYwyeZAK7i6QY8u3WqGVIeGiObjZbhB2Ppq9wwSgfbaz5bUpKPwi6%2F3HRzV60gTURhO%2BOJOrxiuTjF6SKm586HQQizeGKWHlOiJghgO22gaqDlowHDMWuCjkPyk%2Fac1LTXNPFnUlQnbMwnvt7iXSRq6BrpZ7hlxxKZrjLT%2Bb35k4BExmE4XnXS%2BeWiSwNmz74xYtGwBzBjDYJL5KQPJBf%2FmmUqRgCV4xex7f8qtp34F4nLcXC0pRxggkSBBSxm214ubh9j7JZYz5QY8KuGDC9pn%2FeNeqFHaS4B%2FKtkNKzU6YyFmQdiXgFMpK22TpKvDQbeX5%2Bazx2lCqBuIR2MSg8xaVxfVOm14tu0WrqIY8luKV9Vpl23LWs713xhg80XwjkUb1nCOu57Lu0hOODrq1lr21CmJWnU7pttLa6fgT2Sineu%2BwkXeTQuVVBfYOw%2BQgyu6yX7hSkskKFMJPSSvSDgcx%2B0z7ze%2F6wwDfc2j94FtriCv77t7RIN1UQYi4%2FWT%2BH1UtqoHEjwf%2B4WUV4sGnzYnWVVNS9D%2FDuhfIcxMtX%2FeC6GY2xl3DaoInj4Dpn%2F%2B%2B%2BDMJy29J0GOqgBLYwZ%2BS6LeU8LGjYX9awM1lZICDgrQ0hlOV350Z6dYGfgRriIVxT3a1tcWbIoa3i2xkJhWKoJlEjgplRBSMEKhYaLbb9OQjKayNjAfDHGNDGr3%2FeGWuhg7SXAXHa1fs1%2BDqeErCylLFgS3TzFH2D7uTNCiSa6z2QS47PQ5lCYhjWqx9odsrCOmAKTrg23disfNZOaHKnlZaug2Yn7zDgbNneWs%2FKjX5GX&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230110T083848Z&X-Amz-SignedHeaders=content-md5%3Bhost%3Bx-amz-server-side-encryption&X-Amz-Expires=3600&X-Amz-Credential=ASIAXFYJLCYVPNLGNNGA%2F20230110%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=00adb6369887346dafc2fdce630f1527ab9482fb2307c921d2850b0d09c0aace",
        "expiry": "2023-01-10T09:38:48.910Z"
    },
    "status": {
        "code": "uploading"
    },
    "createdAt": "2023-01-10T08:38:48.910Z",
    "modifiedAt": "2023-01-10T08:38:48.910Z"
}

Upload batch file

PUT batchUploadPath

Starts uploading a batch file. Make this request after allocating a batch upload location.

Attribute

Type

Description

Example

batchUploadPath

string

The URI of the upload path.

If you do not know the URI, first allocate a batch upload location. In the response, in the location object, the href key contains the batch upload path.

https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/...

Base64 string

string

The Base64-encoded version of the hex-encoded MD5 checksum. You created the hex-encoded MD5 checksum before you allocated a batch upload location.

hmhSUwGGLymfT1gmfmkCSA==

path to gzipped file

string

The path to the gzipped file. You must upload a file in the body as binary data.

@/C:/Users/user/Desktop/import.json.gz

This request returns an empty, 200 OK response.

Request
curl -X PUT 'https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/...' \
-H 'x-amz-server-side-encryption: AES256' \
-H 'Content-Md5: <Base64_string>' \
-H 'Content-Type: application/gzip' \
--data-binary '<path_to_gzipped_file>'
Request
curl -X PUT 'https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/...' \
-H 'x-amz-server-side-encryption: AES256' \
-H 'Content-Md5: <Base64_string>' \
-H 'Content-Type: application/gzip' \
--data-binary '<path_to_gzipped_file>'

Retrieve batch file upload status

GET /v2/batches/batchRef

Retrieves the current upload status of the batch file that you started uploading.

In the response, if the status is error, the status object contains a log key. The log key contains the URI of the error log. You use the URI of the error log to troubleshoot the upload process by retrieving the error log.

The response body can contain the following fields:

Attribute

Description

Type

href

Echo back of the URL used in this request.

string

ref

UUID of the batch, forms part of the href.

string

checksum

Echo back of checksum of the uploading file.

string

size

Echo back of the size of the uploading file.

integer

location

Details of the file upload location.

object

location.href

The allocated URL to which you upload the batch file. This URL is valid for one hour.

string

location.expiry

Date and time that the upload location href expires.

date time

status

The status of the file upload.

object

status.code

The batch file processing status. Possible values:

  • uploading - the import process was initialized by the client.

  • processing - import file was uploaded and processing has started.

  • success - import file was successfully processed.

  • corrupted - import file did not match the checksum.

  • error - import has failed, see the log file. The location of the log file is the value of the status.log parameter.

string

status.log

If the batch upload request contains errors, the location of the log file that includes details of the errors.

string

summaryStats

Contains a summary of statistics on the file upload.

object

summaryStats.timeToProcessMillis

The amount of time, in milliseconds, that the batch import job took to run.

integer

summaryStats.totalCount

The total number of records read from the import file by the batch import job.

integer

summaryStats.succeededCount

The number of records that the batch import job successfully processed.

integer

summaryStats.failedCount

The number of records that the batch import job failed to process.

integer

createdAt

Date and time the request was created.

date time

modifiedAt

Date and time the request was last updated.

date time

Request
curl -X GET '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \
-u '<username>:<password>' \
-H 'Accept: application/json'
Request
curl -X GET '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \
-u '<username>:<password>' \
-H 'Accept: application/json'
Response

Status: uploading:

JSON
{
    "href": "<baseURL>/v2/batches/12af3453-62da-4b31-b646-631b7b5f3009",
    "ref": "12af3453-62da-4b31-b646-631b7b5f3009",
    "checksum": "b1d600dbf7463924e24647e626cd7c1e",
    "size": 227,
    "location": {
        "href": "https://sitecore-batch-service-production-eu-west-1.s3.eu-west-1.amazonaws.com/pqsTELpfrXBzxKozB0IoL4xuAT0s7WrH/12af3453-62da-4b31-b646-631b7b5f3009/import.gz?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEDAaCWV1LXdlc3QtMSJIMEYCIQCvLllsVnScVKunabp2ecWZ35wWC2qazGUOH38uZ4ebNwIhAPhKsvrNikvkBSJwFo4Heat72zODcLQCPzh87PRThE8qKtUECIn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMNDkzNDAzOTY5MDY2IgzaKR3yFcEnGvR0NjEqqQQiccx7113xYh5boBVgjPQrzpcCLKgXi563nzp0YRIM52WE1LFEezlLQBEcRl9wo0i5ko5%2F8ne%2BPSFGxkc576fPqkdQzQyX9Ub1PA44pwuFzK%2FZSf9mHS7FRqPvvuxlm7srdkceEJK2VAmoUehfKHzDYhtCkPnZyElYwyeZAK7i6QY8u3WqGVIeGiObjZbhB2Ppq9wwSgfbaz5bUpKPwi6%2F3HRzV60gTURhO%2BOJOrxiuTjF6SKm586HQQizeGKWHlOiJghgO22gaqDlowHDMWuCjkPyk%2Fac1LTXNPFnUlQnbMwnvt7iXSRq6BrpZ7hlxxKZrjLT%2Bb35k4BExmE4XnXS%2BeWiSwNmz74xYtGwBzBjDYJL5KQPJBf%2FmmUqRgCV4xex7f8qtp34F4nLcXC0pRxggkSBBSxm214ubh9j7JZYz5QY8KuGDC9pn%2FeNeqFHaS4B%2FKtkNKzU6YyFmQdiXgFMpK22TpKvDQbeX5%2Bazx2lCqBuIR2MSg8xaVxfVOm14tu0WrqIY8luKV9Vpl23LWs713xhg80XwjkUb1nCOu57Lu0hOODrq1lr21CmJWnU7pttLa6fgT2Sineu%2BwkXeTQuVVBfYOw%2BQgyu6yX7hSkskKFMJPSSvSDgcx%2B0z7ze%2F6wwDfc2j94FtriCv77t7RIN1UQYi4%2FWT%2BH1UtqoHEjwf%2B4WUV4sGnzYnWVVNS9D%2FDuhfIcxMtX%2FeC6GY2xl3DaoInj4Dpn%2F%2B%2B%2BDMJy29J0GOqgBLYwZ%2BS6LeU8LGjYX9awM1lZICDgrQ0hlOV350Z6dYGfgRriIVxT3a1tcWbIoa3i2xkJhWKoJlEjgplRBSMEKhYaLbb9OQjKayNjAfDHGNDGr3%2FeGWuhg7SXAXHa1fs1%2BDqeErCylLFgS3TzFH2D7uTNCiSa6z2QS47PQ5lCYhjWqx9odsrCOmAKTrg23disfNZOaHKnlZaug2Yn7zDgbNneWs%2FKjX5GX&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230110T083848Z&X-Amz-SignedHeaders=content-md5%3Bhost%3Bx-amz-server-side-encryption&X-Amz-Expires=3600&X-Amz-Credential=ASIAXFYJLCYVPNLGNNGA%2F20230110%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=00adb6369887346dafc2fdce630f1527ab9482fb2307c921d2850b0d09c0aace",
        "expiry": "2023-01-10T09:38:48.910Z"
    },
    "status": {
        "code": "uploading"
    },
    "createdAt": "2023-01-10T08:38:48.910Z",
    "modifiedAt": "2023-01-10T08:38:49.000Z"
}

Status: error:

JSON
{  
   "href":"<baseURL>/v2/batches/3ee694e5-0b77-2d1e-af19-1aa78f500785",
   "ref":"3ee694e5-0b77-2d1e-af19-1aa78f500785",
   "checksum":"40d9a12f0a3c93c8ed66a3b6f3735790",
   "size":3456,
   "location":{  
      "href":"https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/xyzsla2xze5vxn02kf283wo020jg/3ee694e5-0b77-2d1e-af19-1aa78f500785/import.gz?AWSAccessKeyId=AKIAI2JLVI7OT2L6QDRQ&Expires=1459953714&Signature=yIG7nFv5w%2B2N%2Fkz11Eh7BjqSt2U%3D",
      "expiry":"2023-04-24T09:33:00.770Z"
   },
   "status":{  
      "code":"error",
      "log":"https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/xyzsla2xze5vxn02kf283wo020jg/3ee694e5-0b77-2d1e-af19-1aa78f500785/import.gz?AWSAccessKeyId=AKIAI2JLVI7OT2L6QDRQ&Expires=1459953714&Signature=yIG7nFv5w%2B2N%2Fkz11Eh7BjqSt2U%3D"
   },
   "summaryStats":{  
      "timeToProcessMillis":614867,
      "totalCount":121776,
      "succeededCount":121460,
      "failedCount":316
   },
   "createdAt":"2023-04-24T08:33:00.770Z",
   "modifiedAt":"2023-04-24T08:46:04.000Z"
}

Retrieve batch upload error log

GET errorLogRef

Retrieves the error log. Make this request only if the upload status of a batch file is error.

Attribute

Type

Description

Example

errorLogRef

string

The URI of the error log.

If you do not know the URI, first retrieve the batch file upload status. In the response, if the status is error, the status object contains a log key. The log key contains the URI of the error log.

https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/...

The error log contains error information for each guest record that could not be processed. Records that were processed successfully are not included in the error log.

Logs contain the following information:

  • ref - the unique identifier passed in with the guest record.

  • code - a numeric code that identifies the type of error.

  • message - details about the error type.

Frequent errors you might encounter during the batch file upload process:

Code

Message

Description

400

Validation error

For example, if you are using data extensions, this error might occur because of data inconsistencies, such as:

  • Incorrect data type - the data type assigned to an extension field does not match the type defined for this extension's schema.

  • Undefined attribute - the file includes attributes that do not exist in the schema.

400

Identity information missing

402

Unsupported mode

You are trying to use a mode that is not supported for the Batch API. The supported modes are: insert, create, upsert, merge, delete, gdpr_delete.

  • insert

  • create

  • upsert

  • merge

  • delete

  • gdpr_delete

403

Action not allowed

You do not have sufficient permissions to perform the action, or you are attempting to delete a guest that has a current active session.

404

Resource not found

In a deletion process, you are attempting to delete a guest that does not exist.

409

Resource conflict

In a creation process, you are attempting to create an existing identity.

409

Server error

There is an internal server error, unrelated to the import process.

Request
curl -X GET 'https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/xyzsla2xze5vxn02kf283wo020jg/3ee694e5-0b77-2d1e-af19-1aa78f500785/import.gz?AWSAccessKeyId=AKIAI2JLVI7OT2L6QDRQ&Expires=1459953714&Signature=yIG7nFv5w%2B2N%2Fkz11Eh7BjqSt2U%3D'
Request
curl -X GET 'https://sitecore-batch-service-dev-eu-west-1.s3.amazonaws.com/xyzsla2xze5vxn02kf283wo020jg/3ee694e5-0b77-2d1e-af19-1aa78f500785/import.gz?AWSAccessKeyId=AKIAI2JLVI7OT2L6QDRQ&Expires=1459953714&Signature=yIG7nFv5w%2B2N%2Fkz11Eh7BjqSt2U%3D'
Response

Structure of error logs:

JSON
{"ref": "<UUID>", "code":"<error_code>", "message":"<reason_for_failure>"}

Batch API guest

Guest data model

This topic defines the Sitecore CDP standard data model for the following entities:

When you create a batch file, ensure that you include all required attributes in addition to any guest attributes from the following table:

2.1 data model

Attribute

Description

Type

Example(s)

Insert

Upsert

Migration

firstSeen

The first seen date for the guest.

ISO 8601 Date/Time UTC

"2015-01-01T16:17:16.000Z"

Not supported

Optional

Optional

lastSeen

The last time the guest interacted with your brand.

ISO 8601 Date/Time UTC

"2015-01-01T16:17:16.000Z"

Not supported

Optional

Optional

guestType

A required Sitecore CDP attribute that represents the level of identity obtained.

string (lowercase)

“customer”

Not supported

Optional

Optional

title

The title of the guest.

string (title case)

"Br", "Brigadier", "Capt", "Colonel", "Dame", "Dr", "Elder", "Fr", "General", "Hon", "Judge", "Lord", "Master", "Miss", "Mr", "Mrs", "Ms", "Mstr", "Prof", "Rabbi", "Rev", "Shaikha", "Sheikh", "Sir", "Sister", "Sr"

Not supported

Optional

Optional

firstName

The first name of the guest.

string (title case)

"John"

Not supported

Optional

Optional

lastName

The last name of the guest.

string (recommend title case)

"Does"

Not supported

Optional

Optional

gender

The gender of the guest.

string (lowercase)

"male", "female", "unknown"

Not supported

Optional

Optional

dateOfBirth

The date of birth of the guest.

ISO 8601 Date/Time UTC Validation: Date must be in the past.

"1985-12-24T00:00Z"

Not supported

Optional

Optional

email

The email address of the guest.

string (recommend lowercase)

"john.does@gmail.com"

Not supported

Optional

Optional

phoneNumbers

The phone numbers of the guest.

JSON array of strings

[ "+353161123345", "+353861123311" ]

Not supported

Optional

Optional

language

The preferred language of the guest.

string (2 letter ISO 639 language code)

"EN", "FR", "DE"

Not supported

Optional

Optional

nationality

The nationality of the guest.

string (title case)

"Irish", "British", "Spanish", "French""Irish", "British", "Spanish", "French"

Not supported

Optional

Optional

passportNumber