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.
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 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:
If your organization is using the Engage SDK to integrate, follow the schema for modelling the event data object.
To send additional, custom data with the event, follow the schema for extending the event data object.
To send a custom event, follow the schema for modelling the custom event data object.
If your organization is not using the Engage SDK to integrate, follow the schema for modelling the event data object.
To send additional, custom data with the event, follow the schema for extending the event data object.
To send a custom event, follow the schema for modelling the custom event data object.
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:

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 > Company information > Environment.
Environment | Stream API target endpoint |
---|---|
AP Region |
|
EU Region |
|
US Region |
|
Name of point of sale
To find the name of your point of sale, in Sitecore CDP, on the navigation pane, click > Points of Sale > Name.
Channel, language, and currency
Channel, language, and currency are part of the data you send.
Parameter | Type | Description | Example |
---|---|---|---|
| string (uppercase) | The touchpoint where the user interacts with your brand. For example, for webpages, the channel is See the full list of allowed values. |
|
| 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 |
|
| 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 |
|
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 |
|
Integrating a subdomain only. | beta.myretailsite.com |
|
Integrating a website on 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:
Load the Engage SDK script into your app from a CDN. Choose this if your app uses a tag management system (TMS), for example, Google Tag Manager, or if you can load JavaScript files directly on your website.
Install the Engage SDK package in your app from Node Package Manager (npm). Choose this if you have a modern web development stack, and if you want the option to set cookies from the server and implement server-side tracking.
Before you choose an integration type, consider the following characteristics of the different integration options:
Integration | Characteristics |
---|---|
Client-side integration using the Engage SDK script and a TMS |
|
Client-side integration using the Engage SDK script | |
Integration using the Engage SDK package |
|
Server-side integration using direct HTTP requests |
|
To choose an integration type, select it from the following table:
Your application | Recommended integration type |
---|---|
| Client-side integration using the Engage SDK script and Google Tag Manager |
Web app without TMS | One of the following:
|
Native app without TMS | |
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:
Have collected the required details about your Sitecore CDP instance.
Are familiar with Google Tag Manager and have a workspace there to work with.
This walkthrough describes how to:
Add a tag for the Engage 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:
In Google Tag Manager, click a container.
In the navigation menu, click Tags > New.
In the upper-left corner of the tag pane, enter a name for your tag, for example, Engage SDK.
Click the Tag Configuration card.
In the Choose tag type pane, click Custom HTML.
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.
Click the Triggering card.
In the Choose a trigger pane, click DOM Ready. Your tag pane now looks similar to this:
In the upper-right corner of the tag pane, click Save.
On the main page, in the upper-right corner of the page, click Submit.
In the Submit Changes pane, in the Version Name field, enter a description, for example, Added Engage SDK.
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:
In Google Tag Manager, click the container that you worked on in the previous procedure.
In the navigation menu, click Tags.
In the upper-right corner, click Preview.
On the Tag Assistant page, enter your website's URL, then click Connect. Your website opens in a new window.
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:
In your code editor, open the folder structure of your website.
In the folder where you store your JavaScript files, create a new JavaScript file.
Example:
scripts/sitecore-engage.js
Open the JavaScript file and paste the following Engage SDK script:
// Initialize the engage variable var engage = undefined; // Create and inject the <script> tag into the HTML var s = document.createElement("script"); s.type = "text/javascript"; s.async = true; s.src = "https://d1mj578wat5n4o.cloudfront.net/sitecore-engage-v.1.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.
Save the JavaScript file.
Open the HTML file that imports scripts on every webpage of your website.
Import the JavaScript file that contains the script into the HTML file. Import the JavaScript file as the first
<script>
element before the closing</body>
tag.Important
Depending on the architecture of your website, you might want to place the
<script>
tag elsewhere in your HTML. Where you import the JavaScript file affects the performance of your web experiences and web experiments.Example:
index.html
... <script src="scripts/sitecore-engage.js"></script> <script></script> <script></script> </body> </html>
Verify that the script loads on your website
To verify that the Engage SDK script loads on your website:
In your web browser, open your website and the console. Keep the website and the console open for the rest of this walkthrough.
In the console, enter
engage;
.If an object returns, you have successfully loaded the script on your website.
Send your first VIEW event
After you have verified that the script loads on your website, you collect and send data to Sitecore CDP. You'll send a VIEW event because the VIEW event triggers every time your webpage loads.
To send a VIEW event:
In your code editor, open the JavaScript file that contains the script.
At the bottom of the
s.addEventListener()
function, below theengage = 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.
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:
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
Copy the text.
In Sitecore CDP, click Guests. Paste the copied text into the Search field.
An anonymous guest displays.
This guest is you loading your app just a minute ago. Next, you find the VIEW event associated with this guest.
Click the guest. The guest profile displays.
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:
Have collected the required details about your Sitecore CDP instance.
Have a React app to integrate.
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:
In your terminal, open the root folder of your React app.
Install the Engage SDK by running the following command:
npm install @sitecore/engage
In your code editor, open the root folder of your React app.
In the
src
folder, create a file calledengage.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 }); }; 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
.
In
App.js
, importuseEffect
from React andengage
fromengage.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:
In
App.js
, in theApp
function, call theengage.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.
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:
Have collected the required details about your Sitecore CDP instance.
Have a Next app to integrate.
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:
In your terminal, open the root folder of your Next app.
Install the Engage SDK by running the following command:
npm install @sitecore/engage
In your code editor, open the root folder of your Next app.
In the
pages/api
folder, create a file calledengage.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
.
In the
pages
folder, inindex.js
, importuseEffect
from React andengage
fromengage.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:
In
index.js
, in theHome
function, call theengage.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.
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:
Have collected the required details about your Sitecore CDP instance.
Have a Next app to integrate.
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:
In your terminal, open the root folder of your Next app.
Install the Engage SDK by running the following command:
npm install @sitecore/engage
In your code editor, open the root folder of your Next app.
In the root folder, create a file called
middleware.js
.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 theEngageServer.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:
In the
pages
folder, inindex.js
, importuseEffect
from React andinit
from@sitecore/engage
:import { useEffect } from "react"; import { init } from "@sitecore/engage";
Above the
Home()
function, create an object calledengageSettings
: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.
In the
Home()
function, create an empty, asynchronous functionloadEngage()
, then callloadEngage()
in an Effect Hook. You should use the Effect Hook because thewindow
object has to be present before you load the Engage API. You'll load the Engage API and start sending VIEW events insideloadEngage()
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:
In the
loadEngage()
function, load the Engage API by passingengageSettings
to theinit()
function. Theinit()
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.In the
loadEngage()
function, after you load the Engage API, call theengage.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.
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.
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:
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",
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:
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.
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:
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.
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.
Click the guest. The guest profile displays.
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:
Send other types of events, for example, an IDENTITY event.
Learn more about the browser ID.
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 asundefined
.After the
<script>
tag loads, the asynchronousinit()
function loads the Engage SDK on your webpages. Theengage
variable is reassigned to the return value of theinit()
function.The
settings
object has different attributes than_boxever_settings
in the Boxever JavaScript Library. For example,client_key
is nowclientKey
andtarget
is nowtargetURL
.
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
andtype
are no longer part of the event object.pos
is nowpointOfSale
.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 | |
IDENTITY | |
|
Next steps
You've now successfully upgraded from the Boxever JavaScript Library to the Engage SDK. You initialized the Engage SDK, then updated your scripts for sending events.
Next, you can:
Learn more about sending behavioral and transactional data using the Engage SDK.
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:
VIEW event using the
Engage.pageView()
function (client-side tracking) or theEngageServer.pageView()
function (server-side tracking).The VIEW event captures the user's action of viewing a page in your app.
IDENTITY event using the
Engage.identity()
function (client-side tracking) or theEngageServer.identity()
function (server-side tracking).The IDENTITY event can capture, for example, names, email addresses, and phone numbers.
Custom event using the
Engage.event()
function (client-side tracking) or theEngageServer.event()
function (server-side tracking).You can use custom events to capture any behavior of your choice, for example, clicks and searches.
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:
ADD event - to capture the product details when a user adds a product to their cart.
CONFIRM event - to capture a list of products that are in the cart before the payment is made.
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:
Engage.addToEventQueue()
- to add event objects with a valid payload to the event queue.Engage.processEventQueue()
- to send all the events in the event queue, in the order the events were added. Then, this function empties the event queue.Engage.clearEventQueue()
- to empty the event queue without sending any of the events.
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.

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 asrc
attribute similar tohttps://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 |
---|---|---|
object | Details about your Sitecore CDP instance and cookie settings. |
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); });
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 |
---|---|---|
object | Details about your Sitecore CDP instance and cookie settings. |
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 totrue
. This ensures that cookies are set from the server.The
engageServer
variable is assigned to the return value of theinitServer()
function. That givesengageServer
access to thehandleCookie()
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 |
---|---|---|
| object | The HTTP request. |
| object | The HTTP response. |
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 |
---|---|---|
| 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 |
---|---|---|
object | All the event data. | |
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 |
---|---|---|
object | All the event data. | |
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:
A custom event with custom data of your choice.
Parameters for a standard event
Parameter | Type | Description |
---|---|---|
| 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: |
object | All the event data specific to the standard event type, for example, an ADD event. | |
optional | object | Maximum 50 custom attributes of your choice. |
Parameters for a custom event
Parameter | Type | Description |
---|---|---|
| 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, |
object | The required attributes that every event object must include, and optional attributes that event objects can include. | |
optional | object | Maximum 50 custom attributes of your choice. |
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); };
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);
};
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);
};
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);
};
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);
};
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);
};
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);
};
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 |
---|---|---|
object | All the event data. | |
| object | The HTTP request. |
optional | object | Maximum 50 custom attributes of your choice. |
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 |
---|---|---|
object | All the event data. | |
| object | The HTTP request. |
optional | object | Maximum 50 custom attributes of your choice. |
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:
A custom event with custom data of your choice.
Parameters for a standard event
Parameter | Type | Description |
---|---|---|
| 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: |
object | All the event data specific to the standard event type, for example, an ADD event. | |
| object | The HTTP request. |
optional | object | Maximum 50 custom attributes of your choice. |
Parameters for a custom event
Parameter | Type | Description |
---|---|---|
| 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, |
object | The required attributes that every event object must include, and optional attributes that event objects can include. | |
| object | The HTTP request. |
optional | object | Maximum 50 custom attributes of your choice. |
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; };
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; };
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; };
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; };
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; };
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; };
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; };
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 |
---|---|---|---|
| string (uppercase) | The touchpoint where the user interacts with your brand. For example, for webpages, the channel is | Must be one of:
|
| 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 |
|
| 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 If you specified |
|
Optional attributes
An event data object can optionally include the following attributes:
Attribute | Type | Description | Example |
---|---|---|---|
| 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 The default is |
|
| 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 |
|
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 |
---|---|---|---|
| string | The ID of a personalized page variant. |
|
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.
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"
}
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 |
---|---|---|---|
| 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 |
---|---|---|---|---|
| string | The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system. |
| Required |
| string | The name of your organization's identity system, external to Sitecore CDP, that provided the unique guest identifier. |
| Required |
| string (ISO 8601) | The date the unique guest identifier expires. This is determined by your organization's identity system. |
| Optional |
The object can optionally include personally identifiable information (PII):
Attribute | Type | Description | Example |
---|---|---|---|
| string (lowercase recommended) | The email address of the guest. |
|
| string (title case) | The title of the guest. |
|
| string (title case recommended) | The first name of the guest. |
|
| string (title case recommended) | The last name of the guest. |
|
| string | The gender of the guest. |
|
| string (ISO 8601) | The date of birth of the guest. |
|
| string | The mobile number of the guest. |
|
| string | The phone number of the guest. |
|
| array of strings (title case recommended) | The street address of the guest. |
|
| string (title case recommended) | The city address of the guest. |
|
| string (title case recommended) | The state address of the guest. |
|
| string (uppercase ISO 3166-1 alpha-2) | The country address of the guest. |
|
| string | The postal code of the guest. |
|
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 |
---|---|---|---|
| object | Data about the product that the user adds to the cart. | N/A |
The product
object:
Attribute | Type | Description | Example | Required/optional |
---|---|---|---|---|
| string (title case recommended) | The name of the product that the user added to the cart. |
| Required |
| string (uppercase) | The type of product that the user added to the cart. |
| Required |
| 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 |
| Required |
| string | The ID of the product that the user added to the cart. Used in Analytics for reporting. |
| Required |
| string | An ID generated by your organization to reference the order item. |
| Required |
| string (ISO 8601) Format: | The date and time the user added the product to the cart. |
| Required |
| integer | The number of units of the product that the user added to the cart. Total price = |
| Required |
| float | The unit price of the product. Total price = |
| Required |
| string (uppercase ISO 4217) | The alphabetic currency code of the currency that the product price is specified in. |
| Required |
| float | The unit price of the order item before conversion to the organization's currency. |
| Optional |
| The original currency code for the order item. |
| 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"
}
}
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 |
---|---|---|---|
| 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: "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" }
]
}
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 |
---|---|---|---|
| string (uppercase) | The order ID. |
|
| string (uppercase) | The order status. | Must be one of:
|
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 |
---|---|---|---|
| string | The payment method associated with a checkout. |
|
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 |
---|---|---|---|
| string | The product name the guest searched for. |
|
| string (uppercase) | The product type the guest searched for. |
|
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 tofalse
and pass the settings object to theEngage.init()
function.To set cookies from the server, you must set the
forceServerCookieMode
attribute totrue
and pass the settings object to theEngage.init()
function on the client side, and to theEngage.initServer()
function on the server side.
The settings object includes the following attributes:
Attribute | Type | Description | Example | Required/optional |
---|---|---|---|---|
| string | Your client key. |
| Required |
| string | Your Stream API target endpoint. The value depends on the location of your Sitecore CDP server. | Must be one of:
| Required |
| boolean | Specify whether to add every UTM parameter from the URL of the current webpage to the event object. The default is If |
| Optional |
| string | Your cookie domain. The default is what the browser sets. |
| Optional |
| integer | The number of days before the cookie expires. If you don't specify this value, the cookie expires according to the | For example, set the value to 1 for the cookie to expire in 1 day. | Optional |
| string | A URL path that must exist in the requested URL in order to send the cookie. |
| Optional |
| 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 The default is |
| Optional |
| 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 If you set the value to If you set the value to To customize the loading of the script, set the value to an object. In the object, customize If you received a custom URL from Sitecore to load the web personalization script, specify the URL as a string in the object using The default is |
| Optional on the client side. Not available on the server side. |
| string | The name of the point of sale where the interaction with your brand takes place. If you specified the 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 |
| Required if you specified the |
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 |
---|---|---|
| The | This error can occur when you call Engage functions on the server. Make sure to call Engage functions where the |
| Cannot retrieve the cookie from the server. | See a code sample for setting cookies from the server. |
| Timeout exceeded. The server did not respond within the allotted time. | This error occurs when you call a function with the When you use the |
IV errors
IV
errors are related to incorrect values and wrongly formatted objects in the event data.
Code | Description | Note |
---|---|---|
| Incorrect value for | Set the value to the correct Stream API target endpoint. |
| Incorrect value for Format the value according to ISO 8601. | See examples of correctly formatted data. |
| Incorrect value for | |
| Incorrect value for Format the value according to ISO 8601. | |
| This event supports maximum | |
| Incorrect value for the timeout parameter. Set the value to an integer greater than or equal to |
|
MV errors
MV
errors are related to missing values in the event data.
Code | Description | Note |
---|---|---|
|
| Set the value to your client key. |
|
| Set the value to the correct Stream API target endpoint. |
|
| Set the value to the name of your point of sale. |
|
| See examples of correctly formatted data. |
|
| 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:
In your script, locate your
pointOfSale
attributes. Usually, they are either in your settings object or your event data objects, or both.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 inproduct.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()
, to send data to Sitecore CDP.Boxever.callFlows()
, to get data from Sitecore CDP.
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 |
---|---|---|---|
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. | |
| function | This callback function handles the response. | N/A |
| string | The format of the response. | Set the value to |
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 |
---|---|---|---|
object | Event and experiment data. | Specify the | |
| 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 |
---|---|---|---|
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 | An empty object. | N/A |
| function | This callback function handles the response. | The browser ID is in the The guest reference is in the |
| string | The format of the response. | Set the value to |
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 |
---|---|---|---|
| string | The browser ID. | Set the value to |
| string | The client key. | Set the value to Or, to bypass authentication, set the value to |
| function | This callback function handles the response. | The guest reference is in the |
| string | The format of the response. | Set the value to |
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 |
---|---|---|---|
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 |
---|---|---|---|
| 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 |
---|---|---|---|
| string or number | The name of the cookie. | N/A |
| string | The value of the cookie. | N/A |
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 |
---|---|---|---|
| string | The browser ID. If you are using the Boxever JavaScript Library, set the value to the value that the 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:
|
| string (uppercase) | The touchpoint where the user interacts with your brand. For example, for webpages, the channel is | Must be one of:
|
| 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: |
|
| 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 |
|
| 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 |
|
| string | The name of the webpage where the interaction with your brand takes place. This is a custom value of your choice. |
|
| 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. |
|
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 |
---|---|---|---|---|
| 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 |
---|---|---|---|---|
| string | The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system. |
| Required |
| string | The name of your organization's identity system, external to Sitecore CDP, that provided the unique guest identifier. |
| Required |
| string (ISO 8601) | The date the unique guest identifier expires. This is determined by your organization's identity system. |
| Optional |
The event object for an IDENTITY event can optionally include personally identifiable information (PII):
Attribute | Type | Description | Example | Required/optional |
---|---|---|---|---|
| string (lowercase recommended) | The email address of the guest. |
| Optional |
| string (title case) | The title of the guest. |
| Optional |
| string (title case recommended) | The first name of the guest. |
| Optional |
| string (title case recommended) | The last name of the guest. |
| Optional |
| string | The gender of the guest. |
| Optional |
| string (ISO 8601) | The date of birth of the guest. |
| Optional |
| string | The mobile number of the guest. |
| Optional |
| string | The phone number of the guest. |
| Optional |
| array of strings (title case recommended) | The street address of the guest. |
| Optional |
| string (title case recommended) | The city address of the guest. |
| Optional |
| string (title case recommended) | The state address of the guest. |
| Optional |
| string (uppercase ISO 3166-1 alpha-2) | The country address of the guest. |
| Optional |
| string | The postal code of the guest. |
| 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 |
---|---|---|---|---|
| string | The product type the guest searched for. This is a custom value of your choice, but note that the value |
| Required |
| string | The product name the guest searched for. |
| 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 |
---|---|---|---|---|
| string enum (two-letter, uppercase) | The flight type the guest searched for. | Must be one of:
| Required |
| string (three-letter, uppercase) | The IATA code of the origin the guest searched for. |
| Required |
| string (three-letter, uppercase) | The IATA code of the destination the guest searched for. |
| Required |
| 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. |
| Required |
| 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. |
| Required |
| integer | The number of adults of the flight the guest searched for. The minimum value is |
| Required |
| integer | The number of children of the flight the guest searched for. The minimum value is |
| Required |
| integer | The number of infants of the flight the guest searched for. The minimum value is |
| Required |
| string (title case) | The class of flight the guest searched for. |
| Required |
| string (title case recommended) | The fare family of the flight the guest searched for. |
| 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 |
---|---|---|---|---|
| string | Your client key. |
| Required |
| string | The ID of a live Interactive Full Stack Experience or live Interactive Full Stack Experiment that you want to run. |
| Required |
| string (uppercase) | The touchpoint where the user interacts with your brand. For example, for webpages, the channel is | Must be one of:
| Required |
| 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 |
| Required |
| 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 |
| Required |
| 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. |
| 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 |
---|---|---|---|---|
| string | The browser ID. If you are using the Boxever JavaScript Library, set the value to the value that the 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:
| Required if none of the other attributes in this table are part of the flow object. |
| string (lowercase recommended) | The email address of the guest. |
| Required if none of the other attributes in this table are part of the flow object. |
| 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 |
---|---|---|---|---|
| string | The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system. |
| Required |
| string | The name of your organization's identity system, external to Sitecore CDP, that provided the unique guest identifier. |
| Required |
| string (ISO 8601) | The date the unique guest identifier expires. This is determined by your organization's identity system. |
| Optional |
Optional attributes for flow objects
The flow object can optionally contain custom objects of your choice:
Attribute | Type | Description | Example | Required/optional |
---|---|---|---|---|
| object | An object of your choice. |
| 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:
Locate your library script.
For the
client_key
key, specify the correct client key.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:
Locate your library script.
For the
javascriptLibraryVersion
key, set the value to "1.4.9".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:
In your library script, locate all event objects.
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:
In your library script, locate all event objects.
Make sure each event object contains a
browser_id
.Set the value of
browser_id
to the value that theBoxever.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:
In your library script, locate all event objects.
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:
Locate your library script.
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 |
1.4.8 | Adds compatibility with v1.3 Browser Service. Removes support for Internet Explorer 11. |
1.4.6 | Includes the optional |
1.4.5 | If the |
1.4.4 | Removes support of the |
1.4.3 | Adds the |
1.4.2 | Adds the |
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 > Company information > Environment.
Environment | Base URL |
---|---|
AP Region |
|
EU Region |
|
US Region |
|
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.
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 |
---|---|---|---|
| string | Your client key. |
|
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'
{ "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 |
---|---|---|---|
| string | Your client key. |
|
| JSON object | All the event details. |
|
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 |
---|---|---|---|
| string (uppercase) | The touchpoint where the user interacts with your brand. For example, for webpages, the channel is | Must be one of:
|
| 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: |
|
| 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 |
|
| 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 |
|
| string | The name of the webpage where the interaction with your brand takes place. This is a custom value of your choice. |
|
| 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. |
|
| string | The browser ID. | The browser ID is a string similar to:
|
{"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",}
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"}'
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"}'
{
"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 |
---|---|---|---|
| string (uppercase) | The touchpoint where the user interacts with your brand. |
|
| string (uppercase) | The type of the event that takes place when the user interacts with your brand. |
|
| string (uppercase ISO 639-1) | The language the user is using your app in. |
|
| string (uppercase ISO 4217) | The alphabetic currency code of the currency the user is using in your app. |
|
| string | The name of the webpage where the interaction with your brand takes place. This is a custom value of your choice. |
|
| string | The name of the point of sale where the interaction with your brand takes place. |
|
| string | The browser ID. |
|
{ "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 |
---|---|---|---|---|
| JSON object | JSON Object An object of arbitrary session data. | N/A | Required |
| Any of the following:
| One or many name/value pair attributes for custom session data. |
| Optional |
{ "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.
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
{ "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
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" }] }
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" }
{ "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.
{ "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" }
{ "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.
{ "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" } }
{ "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 |
---|---|---|---|---|
| The channel captured on each page the guest visited. | string |
| Required |
| The type of event. | string (uppercase) |
| Required |
| The language captured on each page the guest visited. | string (2 letter ISO 639 language code) |
| Required |
| The type of currency. | string (3 letter ISO 4217) |
| Required |
| The name of the webpage the guest visited. | string |
| Required |
| The point of sale (storefront) captured on each page the guest visited. | string (predefined by client) |
| Required |
| The ID of a browser generated by Sitecore CDP. | string (UUID) |
| Required |
| The JSON object that contains the product entity data. | JSON object | N/A | Required |
| The type of product added to cart. | string (uppercase) |
| Required |
| The item ID of the product added to the cart. Used in ETL to create the order. | string |
| Required |
| The name of the product added to the cart. | string (suggest title case) |
| Required |
| The currency of the product added to the cart. | string (3 letter ISO 4217) |
| Required |
| The unit price of the product. Total price of the product is calculated by unit price multiplied by quantity. | number |
| Required |
| The number of unit added. Total price of the product is calculated by unit price multiplied by quantity. | integer |
| Required |
| The product ID of the product added. Used in Analytics for reporting. | string (suggest title case) |
| Required |
| The IATA code (airport only) of the flight origin. | string (IATA airport code) |
| Required |
| The IATA code (airport only) of the flight destination. | string (IATA airport code) |
| Required |
| The type of flight. | string (uppercase) |
| Required |
| The passenger type of flight ticket. | string (uppercase) |
| Required |
| The JSON object that contains the flight segment entity data. | JSON object | N/A | Required |
| The IATA code (airport only) of the flight segment origin. | string (IATA airport code) |
| Required |
| The IATA code (airport only) of the flight segment destination. | string (IATA airport code) |
| Required |
| 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 |
| Required |
| 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 |
| Required |
| The number of the carrier. | string |
| Required |
| The marketing carrier code of the flight segment. | 2 character IATA carrier code (uppercase) |
| Required |
| The fare class of the flight segment. | string (title case) |
| Required |
| The equipment type relevant to the flight segment. | string |
| Optional |
| The fare family of the flight segment. | string (suggest title case) |
| 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.
{ "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 |
---|---|---|---|
| string (uppercase) | The touchpoint where the user interacts with your brand. |
|
| string (uppercase) | The type of the event that takes place when the user interacts with your brand. |
|
| string (uppercase ISO 639-1) | The language the user is using your app in. |
|
| string (uppercase ISO 4217) | The alphabetic currency code of the currency the user is using in your app. |
|
| string | The name of the webpage where the interaction with your brand takes place. This is a custom value of your choice. |
|
| string | The name of the point of sale where the interaction with your brand takes place. |
|
| string | The browser ID. |
|
| array of objects | The consumer data. | N/A |
The consumer
array of objects:
Attribute | Type | Description | Example | Required/optional |
---|---|---|---|---|
| string (title case) | The title of the consumer. |
| Required |
| string (title case recommended) | The first name of the consumer. |
| Required |
| string (title case recommended) | The last name of the consumer. |
| Required |
| string | The gender of the consumer. |
| Optional |
| string (ISO 8601) | The date of birth of the consumer. |
| Optional |
| string | The mobile number of the consumer. |
| Optional |
| string (title case) | The nationality of the consumer. |
| Optional |
| string | The reference ID of the consumer. |
| Optional |
| array of strings | A list of item IDs of core and dependent products that belong to the consumer. |
| Optional |
{ "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
{ "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:
{ "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"} ] }
{ "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 |
---|---|---|---|---|
| The channel captured on each page the guest visited. | string (uppercase) |
| Required |
| The type of event. | string (uppercase) |
| Required |
| The language captured on each page the Guest visited. | string (2 letter ISO 639 language code) |
| Required |
| The type of currency. | string (3 letter ISO 4217) |
| Required |
| The name of the webpage the guest visited. | string |
| Required |
| The point of sale (storefront) captured on each page the guest visited. | string (predefined by the client) |
| Required |
| The ID of a browser generated by Sitecore CDP. | string (UUID) |
| Required |
| A JSON array containing a list of | JSON array |
| Required |
| The item ID of the product to be confirmed as purchased. | string |
| Required |
2.0 data model
Attribute | Description | Type | Example(s) | Required/optional |
---|---|---|---|---|
| The channel captured on each page the guest visited. | string (uppercase) |
| Required |
| The type of event. | string (uppercase) |
| Required |
| The language captured on each page the Guest visited. | string (2 letter ISO 639 language code) |
| Required |
| The type of currency. | string (3 letter ISO 4217) |
| Required |
| The name of the webpage the guest visited. | string |
| Required |
| The point of sale (storefront) captured on each page the guest visited. | string (predefined by the client) |
| Required |
| The ID of a browser generated by Sitecore CDP. | string (UUID) |
| Required |
| A JSON array containing a list of | JSON array |
| Required |
| The item ID of the product to be confirmed as purchased. | string |
| 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 |
---|---|---|---|
| string (uppercase) | The touchpoint where the user interacts with your brand. |
|
| string (uppercase) | The type of the event that takes place when the user interacts with your brand. |
|
| string (uppercase ISO 639-1) | The language the user is using your app in. |
|
| string (uppercase ISO 4217) | The alphabetic currency code of the currency the user is using in your app. |
|
| string | The name of the webpage where the interaction with your brand takes place. This is a custom value of your choice. |
|
| string | The name of the point of sale where the interaction with your brand takes place. |
|
| string | The browser ID. |
|
| string (uppercase) | The reference of the order. |
|
| string enum | The status of the order. |
|
{ "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
{ "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.
{ "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 |
---|---|---|---|
| string (uppercase) | The touchpoint where the user interacts with your brand. |
|
| 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: |
| string (uppercase ISO 639-1) | The language the user is using your app in. |
|
| string (uppercase ISO 4217) | The alphabetic currency code of the currency the user is using in your app. |
|
| string | The name of the webpage where the interaction with your brand takes place. This is a custom value of your choice. |
|
| string | The name of the point of sale where the interaction with your brand takes place. |
|
| string | The browser ID. |
|
{ "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" }
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 haveorderedAt
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:
A guest adds an item to their cart.
An ADD event is sent to Sitecore CDP.
The guest's session closes manually, by timing out, or by network latency.
Sitecore CDP sets the stream session
cartType
toABANDONED
.If configured, Sitecore Personalize sends a triggered experience.
The following steps result in a CLEAR_CART event being sent to Sitecore CDP:
A guest adds an item to their cart.
An ADD event is sent to Sitecore CDP.
The guest removes the item or items from their cart.
A CLEAR_CART event is sent to Sitecore CDP.
The guest's session closes manually, by timing out, or by network latency.
Sitecore CDP sets the stream session
cartType
toCLOSED
.Sitecore Personalize does not send the triggered experience.
2.0 data model
Send additional event data
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 } }
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:
For the
stream_api_target_endpoint
parameter, specify the correct Stream API target endpoint.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:
In the HTTP request, in the
message
query parameter, locate the key-value pairs that describe the event.For the
browser_id
key, specify the browser ID that you previously retrieved.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:
In the HTTP request, in the
message
query parameter, locate the key-value pairs that describe the event.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:
In the HTTP request, in the
message
query parameter, locate the key-value pairs that describe the event.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.

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 > Company information > Environment.
Environment | Base URL |
---|---|
AP Region |
|
EU Region |
|
US Region |
|
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 > API access:
The user name is the Client Key.
The password is the API Token.
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 |
---|---|---|
| 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. |
| string Must be one of:
| The type of record contained in the |
| string Must be one of:
| Indicates how to import the record into the system:
|
| 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.
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:
Have a JSON file (
import.json
) that contains valid JSON records. If you do not have your own JSON records, you can use our sample JSON records.Have access to a file archiver.
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:
Use either a file archiver or a programmatic approach.
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 ( |
|
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. |
|
Base64 string | string | The same hex-encoded MD5 checksum, converted to Base64. |
|
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. |
|
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:
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, thehref
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/...
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.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 isprocessing
. After the upload succeeds, the status issuccess
.
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:
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.
Click the guest. The guest profile displays.
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 theExt
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 |
---|---|---|---|
| string | A hex-encoded MD5 checksum for the gzipped file. This is to provide assurance that the integrity of the gzipped file is intact. |
|
| integer | The size in bytes of the gzipped file ( |
|
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 |
---|---|---|
| Echo back of the URL used in this request. | string |
| UUID of the batch, forms part of the href. | string |
| Echo back of checksum of the uploading file. | string |
| Echo back of the size of the uploading file. | integer |
| Details of the file upload location. | object |
| The allocated URL to which you upload the batch file. This URL is valid for one hour. | string |
| Date and time that the upload location href expires. | date time |
| The status of the file upload. | object |
| The batch file processing status. Possible values:
| string |
| Date and time the request was created. | date time |
| Date and time the request was last updated. | date time |
curl -X PUT '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \ -u '<username>:<password>' \ -H 'Accept: application/json' \ --data-raw ' { "checksum": "b1d600dbf7463924e24647e626cd7c1e", "size": 227 }'
curl -X PUT '<baseURL>/v2/batches/12af3453-62da-4b31-a646-631b7b5f3009' \ -u '<username>:<password>' \ -H 'Accept: application/json' \ { "checksum": "b1d600dbf7463924e24647e626cd7c1e", "size": 227 }'
location.href
contains the batch upload path:
{ "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 |
---|---|---|---|
| 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 |
|
| 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. |
|
| string | The path to the gzipped file. You must upload a file in the body as binary data. |
|
This request returns an empty, 200 OK
response.
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>'
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 |
---|---|---|
| Echo back of the URL used in this request. | string |
| UUID of the batch, forms part of the href. | string |
| Echo back of checksum of the uploading file. | string |
| Echo back of the size of the uploading file. | integer |
| Details of the file upload location. | object |
| The allocated URL to which you upload the batch file. This URL is valid for one hour. | string |
| Date and time that the upload location href expires. | date time |
| The status of the file upload. | object |
| The batch file processing status. Possible values:
| string |
| If the batch upload request contains errors, the location of the log file that includes details of the errors. | string |
| Contains a summary of statistics on the file upload. | object |
| The amount of time, in milliseconds, that the batch import job took to run. | integer |
| The total number of records read from the import file by the batch import job. | integer |
| The number of records that the batch import job successfully processed. | integer |
| The number of records that the batch import job failed to process. | integer |
| Date and time the request was created. | date time |
| Date and time the request was last updated. | date time |
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'
Status: uploading
:
{ "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
:
{ "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 |
---|---|---|---|
| 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 |
|
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 |
---|---|---|
|
| For example, if you are using data extensions, this error might occur because of data inconsistencies, such as:
|
|
| |
|
| You are trying to use a mode that is not supported for the Batch API. The supported modes are:
|
|
| You do not have sufficient permissions to perform the action, or you are attempting to delete a guest that has a current active session. |
|
| In a deletion process, you are attempting to delete a guest that does not exist. |
|
| In a creation process, you are attempting to create an existing identity. |
|
| There is an internal server error, unrelated to the import process. |
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'
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'
Structure of error logs:
{"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 |
---|---|---|---|---|---|---|
| The first seen date for the guest. | ISO 8601 Date/Time UTC |
| Not supported | Optional | Optional |
| The last time the guest interacted with your brand. | ISO 8601 Date/Time UTC |
| Not supported | Optional | Optional |
| A required Sitecore CDP attribute that represents the level of identity obtained. | string (lowercase) |
| Not supported | Optional | Optional |
| The title of the guest. | string (title case) |
| Not supported | Optional | Optional |
| The first name of the guest. | string (title case) |
| Not supported | Optional | Optional |
| The last name of the guest. | string (recommend title case) |
| Not supported | Optional | Optional |
| The gender of the guest. | string (lowercase) |
| Not supported | Optional | Optional |
| The date of birth of the guest. | ISO 8601 Date/Time UTC Validation: Date must be in the past. |
| Not supported | Optional | Optional |
| The email address of the guest. | string (recommend lowercase) |
| Not supported | Optional | Optional |
| The phone numbers of the guest. | JSON array of strings |
| Not supported | Optional | Optional |
| The preferred language of the guest. | string (2 letter ISO 639 language code) |
| Not supported | Optional | Optional |
| The nationality of the guest. | string (title case) |
| Not supported | Optional | Optional |
|