Sitecore Personalize developer documentation
Welcome to the new Sitecore Personalize developer documentation
We updated the Sitecore Personalize developer documentation with the following changes:
To align with the business decision to separate the Sitecore CDP and Sitecore Personalize apps, Sitecore CDP developer documentation is no longer published on the same site as Sitecore Personalize developer documentation.
We updated code examples with more relevant values.
Your success using this documentation is important to us. Send feedback about the documentation to docsite@sitecore.net.
What's new
The latest updates for Sitecore Personalize APIs.
February 2023
The new Engage JavaScript Library and Engage SDK are modern, easy-to-use tools that help you integrate your application with Sitecore Personalize. The updated Integrating with Sitecore Personalize section describes how to use these tools.
Overview
Sitecore Personalize lets you personalize customer interactions, run experiments, and deliver personalized experiences across all the digital channels of your organization.
The Stream API lets you send real-time behavioral and transactional data about the users of your application to Sitecore Personalize.

Data models
This documentation describes Sitecore Personalize functionality for two different data models: 2.1 data model and 2.0 data model.
If your organization purchased Sitecore Personalize after March 2021, your instance of Sitecore Personalize is using the 2.1 data model. To use this documentation, make sure that the 2.1 button is selected at the top of the right-hand pane.
If your organization purchased Boxever before 2021, your instance of Sitecore Personalize is probably using the 2.0 data model. To use this documentation, click the 2.0 button at the top of the right-hand pane.
Before you start sending data
Before you start sending data to Sitecore Personalize, you must identify the type of API you want to use and ensure you model the data correctly for the API and data model version of your organization's tenant, 2.1 data model or 2.0 data model.
Sitecore APIs are flexible by-design. To ensure that the data is available for users to leverage in personalization and decisioning, you must follow the data model schema for the specific API.
We recommend that you read the following topics to learn about the APIs and how to model the data:
Sending events
Use the Stream API to collect and send behavioral data to Sitecore Personalize in real time. The behavioral data can include guest's page views, clicks, searches, and identifiers.
Your organization can send additional, custom data with events and use that data in real-time personalization and decisioning.
To ensure that you can access event data in the UI, including custom data, you must model the event object, and the optional event data extensions and custom events, according to your organization's integration:
If your organization is using the Engage JavaScript Library or 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 Engage JavaScript Library or 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 Personalize provides different APIs for sending orders to Sitecore Personalize. The available options depend on different factors including whether orders are submitted in real-time, offline, or synchronously.
This topic provides information on how to model the different order objects depending on the API, integration option, and data model that your organization is using, 2.1 data model or 2.0 data model.
We recommend that you read this topic before you start sending order data, to ensure that users can use the order data in personalization and decisioning. If you do not model the order data correctly, it might not be available in the UI even if you were able to successfully send it to Sitecore Personalize.
Managing orders in real-time
Use the Stream API to collect and send order data in real-time to Sitecore Personalize, including when an order is created. There are several order-related events you can send as a guest interacts with your site, for example, when a guest adds a product to their shopping cart, makes a purchase, or empties their shopping cart.
To ensure that the order is created, you must send the required events, in the correct order, and model the event object based on one of the following integration options:
If your organization is using the Engage JavaScript Library or the Engage SDK to integrate, see sending orders for details on the events that are required to create an order. This is the preferred method for sending orders to Sitecore Personalize.
If your organization is not using the Engage JavaScript Library or the Engage SDK to integrate, see sending orders for details on the events that are required to create an order.
Stream API
The Stream API lets you send real-time behavioral and transactional data about the users of your application to Sitecore Personalize. Using the Stream API involves integrating your application with Sitecore Personalize.
We recommend that you integrate using the Engage JavaScript Library or the Engage SDK, depending on your business needs.
Overview
Sitecore Personalize provides a suite of API services that makes data management easier, faster, and more efficient. The Stream API captures fast-flowing, high-velocity event data at the same time that it is generated on your organization's website. When you integrate your application using the Engage JavaScript Library or the Engage SDK, the library and the SDK use the Stream API behind the scenes to facilitate the capturing of events. The Stream API can also be deployed in conjunction with your organization's data layer.
The Stream API consists of two APIs. If you integrate your application using direct HTTP requests, you make requests to both of the following APIs:
Browser API - the Browser Interface enables you to extend functionality within a web browser or other HTTP client. You can use the Browser Interface to manage cookies in the browser that help identify guests and facilitate personalization.
Event API - the Event Interface enables event processing. For example, you can use the Event API to send events in at speed from mobile applications or your website.
The Stream API has the following characteristics:
Supports synchronous calls
Sends write-only data
Processes structured data
Captures online events
Facilitates Online Data Capture (ODC)
When to use the Stream API
The Stream API provides a light-touch integration that facilitates the immediate realization of Sitecore Personalize functionality. The Stream API is used for the following purposes:
Online data capture - you can integrate the Stream API with your data layer to capture guest activity as guests navigate your online booking flow. Sitecore Personalize can also integrate with your website, mobile app, and call center.
Website personalization - your organization's web-based application can pass guest, behavioral, and transactional data to Sitecore Personalize to use in real-time decisioning and experience execution.
Behavioral information - the Event API captures a guest's behavioral data that can immediately be used in real-time personalization. These are events, for example, the pages the guest visits, the searches the guest performs, purchased products, and products added to the cart but not purchased.
Optimizes decisioning - the Stream API captures behavioral and transactional data to ensure that decisioning has the most up-to-date guest, order, and search data for use in personalization and experiments.
Integrating with Sitecore Personalize
Sitecore Personalize captures behavioral and transactional data about users as they interact with an application. To collect this data and send it to Sitecore Personalize, you first have to integrate your app with Sitecore Personalize.
We recommend that you integrate using the Engage JavaScript Library or the Engage SDK, depending on your business needs.
During integration
During integration, you start collecting and sending real-time behavioral and transactional data to Sitecore Personalize using the Stream API:

For example, the data can include:
A user's page views.
A user's clicks, searches, and other actions.
A user's identifiers when they register or log in.
Items the user adds to their shopping cart.
Order details.
Geolocation details.
After integration
After integrating, Sitecore Personalize starts capturing the behavioral and transactional data from your app. You can then act on that data by:
Running experiments to determine which content resonates the most with each user.
Personalizing user interactions.
Preparing to integrate
Before you integrate with Sitecore Personalize, you have to:
Collect required details about your Sitecore Personalize instance.
Choose an integration type.
Collect required details
During integration, you have to provide details about your Sitecore Personalize instance. You should collect the necessary information before you start integrating.
Client key
The client key is your organization's unique and public identifier.
Stream API target endpoint
When you integrate, you send data using the Stream API. Your Stream API target endpoint depends on the environment of your Sitecore Personalize instance.
To find the environment, in Sitecore Personalize, on the navigation pane, click > 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 Personalize, 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 JavaScript Library or the Engage SDK, you can specify your cookie domain. The cookie domain is the top-level domain of the website you are integrating. The cookie domain ensures that Sitecore Personalize stores cookies in the web browser as first-party cookies.
Scenario | Example domain | Cookie domain |
---|---|---|
Integrating the main domain, including all subdomains. | www.myretailsite.com |
|
Integrating a subdomain only. | beta.myretailsite.com |
|
Integrating a website on localhost. | localhost |
|
Web personalization (optional)
Decide whether you want to run personalization with Sitecore Personalize. This affects how you initialize the Engage JavaScript Library or the Engage SDK.
Choose an integration type
Sitecore Personalize offers various integration options. In general, we recommend that you integrate using either the Engage JavaScript Library or the Engage SDK:
The Engage JavaScript Library lets you integrate using a CDN link. Choose the Engage JavaScript Library if your app uses a tag management system (TMS), for example, Google Tag Manager, or if you can load JavaScript files directly on your website.
The Engage SDK lets you integrate using a JavaScript package manager, for example, npm. Choose the Engage SDK if you have a modern web development stack, and if you want the option to set cookies from the server and implement server-side tracking.
Before you choose an integration type, consider the following characteristics of the different integration options:
Integration | Characteristics |
---|---|
Client-side integration using the Engage JavaScript Library and a TMS |
|
Client-side integration using the Engage JavaScript Library | |
Integration using the Engage SDK |
|
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 JavaScript Library 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, we recommend that you upgrade to the Engage JavaScript Library.
Walkthrough: Integrating using the Engage JavaScript Library and Google Tag Manager
This topic walks you through integrating your website using the Engage JavaScript Library and Google Tag Manager (GTM).
This walkthrough assumes that you:
Have collected the required details about your Sitecore Personalize instance.
Are familiar with Google Tag Manager and have a workspace there to work with.
This walkthrough describes how to:
Add a tag for the Engage JavaScript Library to your website.
Verify that the library loads on your website.
Add more tags to your website.
Add a tag for the Engage JavaScript Library to your website
The first step to integrating your website is to configure and publish a new Google Tag Manager tag for your website. The tag contains the Engage JavaScript Library script and fires when the DOM is ready. The script initializes the Engage JavaScript Library and sends VIEW events from your website.
To add a tag to your website:
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 JavaScript Library.
Click the Tag Configuration card.
In the Choose tag type pane, click Custom HTML.
In the HTML code block, paste the following Engage JavaScript Library script:
<script> // Initialize the engage variable var engage = undefined; // Create and inject the <script> tag into the HTML var s = document.createElement("script"); s.type = "text/javascript"; s.async = true; s.src = "https://d1mj578wat5n4o.cloudfront.net/sitecore-engage-v.1.3.0.min.js"; var x = document.querySelector("script"); x.parentNode.insertBefore(s, x); // Initialize the Engage JavaScript Library s.addEventListener("load", function () { var settings = { clientKey: "<client_key_PLACEHOLDER>", targetURL: "<stream_api_target_endpoint_PLACEHOLDER>", pointOfSale: "<point_of_sale_PLACEHOLDER>", cookieDomain: "<cookie_domain_PLACEHOLDER>", cookieExpiryDays: 365, forceServerCookieMode: false, includeUTMParameters: true, webPersonalization: "<boolean_or_object>" }; window.Engage.init(settings).then(function (result) { engage = result; // Send a VIEW event var event = { channel: "<channel_PLACEHOLDER>", language: "<language_PLACEHOLDER>", currency: "<currency_PLACEHOLDER>", page: "<page_PLACEHOLDER>" }; engage.pageView(event); }); }); </script>
Replace the placeholder values with the required details from your Sitecore Personalize instance.
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 JavaScript Library.
Click Publish. Your website now loads the Engage JavaScript Library and sends VIEW events.
Verify that the library loads on your website
After you have added the tag, you can preview your Google Tag Manager container and verify that the tag for the Boxever JavaScript Library fires on your website.
To verify that the library loads on your website:
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 library on your website and sent a VIEW event.
Add more tags to your website
The Engage JavaScript Library now loads on your website, and collects and sends VIEW events. To collect and send other event data, you can add tags to send other events.
Next steps
You've now successfully integrated your website with Sitecore Personalize. You sent an event from your website, and Sitecore Personalize now captures data about your users in real time.
Walkthrough: Integrating using the Engage JavaScript Library
This topic walks you through integrating your website using the Engage JavaScript Library.
This walkthrough assumes that you:
Have collected the required details about your Sitecore Personalize instance.
Are familiar with HTML, JavaScript, and your web browser's developer tools.
Have a website to integrate.
This walkthrough describes how to:
Load the library on your website.
Verify that the library loads on your website.
Send your first VIEW event.
Verify that Sitecore Personalize captured your VIEW event.
Load the library on your website
The first step to integrating your website is to load the library script on every webpage of your website using the HTML <script>
tag.
To load the library:
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-library.js
Open the JavaScript file and paste the following Engage JavaScript Library script:
// Initialize the engage variable var engage = undefined; // Create and inject the <script> tag into the HTML var s = document.createElement("script"); s.type = "text/javascript"; s.async = true; s.src = "https://d1mj578wat5n4o.cloudfront.net/sitecore-engage-v.1.3.0.min.js"; var x = document.querySelector("script"); x.parentNode.insertBefore(s, x); // Initialize the Engage JavaScript Library s.addEventListener("load", async () => { var settings = { clientKey: "<client_key_PLACEHOLDER>", targetURL: "<stream_api_target_endpoint_PLACEHOLDER>", pointOfSale: "<point_of_sale_PLACEHOLDER>", cookieDomain: "<cookie_domain_PLACEHOLDER>", cookieExpiryDays: 365, forceServerCookieMode: false, includeUTMParameters: true, webPersonalization: "<boolean_or_object>" }; engage = await window.Engage.init(settings); // Send a VIEW event // ... });
Replace the placeholder values with the required details from your Sitecore Personalize instance.
Save the JavaScript file.
Open the HTML file that imports scripts on every webpage of your website.
Import the JavaScript file that contains the library script into the HTML file. Import the JavaScript file as the first
<script>
element before the closing</body>
tag.Important
Depending on the architecture of your website, you might want to place the
<script>
tag elsewhere in your HTML. Where you import the JavaScript file affects the performance of your web experiences and web experiments.Example:
index.html
... <script src="scripts/sitecore-engage-library.js"></script> <script></script> <script></script> </body> </html>
Verify that the library loads on your website
To verify that the library loads on your website:
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 library on your website.
Send your first VIEW event
After you have verified that the library loads on your website, you collect and send data to Sitecore Personalize. You'll send a VIEW event because the VIEW event triggers every time your webpage loads.
To send a VIEW event:
In your code editor, open the JavaScript file that contains the library 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 Personalize > Developer center > Event viewer > Search field:"); console.log("bid:", engage.getBrowserId());
Replace the placeholder values with the required details from your Sitecore Personalize instance.
This script creates a VIEW event object and sends the event data to Sitecore Personalize immediately after the component renders for the first time. It also logs the browser ID to the console. You'll use the browser ID in the next procedure to find the VIEW event in Sitecore Personalize.
In your web browser, reload the webpage. The VIEW event triggers and the event data is sent.
Verify that Sitecore Personalize captured your VIEW event
After you have sent a VIEW event, you log in to Sitecore Personalize and find the event.
To verify that Sitecore Personalize captured your VIEW event:
In your web browser's console, find a text similar to:
bid: a38b230c-11eb-4cf9-8d5d-274e9f344925
Tip
This text consists of the
bid:
prefix plus a browser ID.In Sitecore Personalize, to find your users by the browser ID, always use the
bid:
prefix plus the browser ID notation. For example:bid: a38b230c-11eb-4cf9-8d5d-274e9f344925
Copy the text.
In Sitecore Personalize, click Developer center > Event viewer. Paste the copied text into the Search field. A list of events associated with this guest displays. The list contains a VIEW event. This is the event that was triggered in a previous procedure.
Note
If you have both Sitecore CDP and Sitecore Personalize, you can find the data in Guests.
Next steps
You've now successfully integrated your website with Sitecore Personalize. You sent an event from your website and verified that Sitecore Personalize captures data about your users in real time.
Walkthrough: Integrating a React app using the Engage SDK
This topic walks you through integrating your React app using the Engage SDK.
This walkthrough assumes that you:
Have collected the required details about your Sitecore Personalize 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 Personalize captured your VIEW event.
Install and initialize @sitecore/engage
The first step to integrating your app is to install and initialize the @sitecore/engage
package.
To install and initialize the package:
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 Personalize instance.
This script:
Imports the
init()
function from the@sitecore/engage
package.Asynchronously loads the Engage API using details about your Sitecore Personalize instance and sets cookies from the client.
Exports your instance of the Engage API as a variable called
engage
.
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 Personalize. 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 Personalize > Developer center > Event viewer > Search field:"); console.log("bid:", engage.getBrowserId()); }; }; return <></>; }
Replace the placeholder values with the required details from your Sitecore Personalize instance.
This script creates a VIEW event object and sends the event data to Sitecore Personalize immediately after the component renders for the first time. It also logs the browser ID to the console. You'll use the browser ID in the next procedure to find the VIEW event in Sitecore Personalize.
In your terminal, enter
npm start
to start your React app. When the webpage loads, the VIEW event triggers and the event data is sent.
Verify that Sitecore Personalize captured your VIEW event
Next steps
You've now successfully integrated your app with Sitecore Personalize. You sent an event from your app and verified that Sitecore Personalize captures data about your users in real time.
Walkthrough: Integrating a Next app using the Engage SDK (client-set cookies)
This topic walks you through integrating your Next app using the Engage SDK.
In this walkthrough, you'll use client-set cookies.
This walkthrough assumes that you:
Have collected the required details about your Sitecore Personalize 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 Personalize captured your VIEW event.
Install and initialize @sitecore/engage
The first step to integrating your app is to install and initialize the @sitecore/engage
package.
To install and initialize the package:
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 Personalize instance.
This script:
Imports the
init()
function from the@sitecore/engage
package.Asynchronously loads the Engage API using details about your Sitecore Personalize instance and sets cookies from the client.
Exports your instance of the Engage API as a variable called
engage
.
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 Personalize. 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 Personalize > Developer center > Event viewer > Search field:"); console.log("bid:", engage.getBrowserId()); }; }; }
Replace the placeholder values with the required details from your Sitecore Personalize instance.
This script creates a VIEW event object and sends the event data to Sitecore Personalize immediately after the component renders for the first time. It also logs the browser ID to the console. You'll use the browser ID in the next procedure to find the VIEW event in Sitecore Personalize.
In your terminal, enter
npm run dev
to start your Next app. When the webpage loads, the VIEW event triggers and the event data is sent.
Verify that Sitecore Personalize captured your VIEW event
Next steps
You've now successfully integrated your app with Sitecore Personalize. You sent an event from your app and verified that Sitecore Personalize captures data about your users in real time.
Walkthrough: Integrating a Next app using the Engage SDK (server-set cookies)
This topic walks you through integrating your Next app using the Engage SDK.
In this walkthrough, you'll use server-set cookies.
This walkthrough assumes that you:
Have collected the required details about your Sitecore Personalize 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 Personalize captured your VIEW event.
Install and initialize @sitecore/engage on the server side
The first step to integrating your app is to install and initialize the @sitecore/engage
package in your web server. This step involves setting cookies from the server and sending them to the client.
To install and initialize the package on the server side:
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 Personalize instance.
This script:
Initializes the Engage SDK in a middleware function on the server using the
initServer()
function.Collects the details about your Sitecore Personalize instance and cookie settings in the
engageSettings
object, and passes the object to 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 Personalize 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 Personalize. 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 Personalize > Developer center > Event viewer > Search field:"); console.log("bid:", engage.getBrowserId()); };
You'll use the browser ID in the next procedure to find the VIEW event in Sitecore Personalize.
In your terminal, enter
npm run dev
to start your Next app. When the webpage loads, the VIEW event triggers and the event data is sent.
Verify that Sitecore Personalize captured your VIEW event
Next steps
You've now successfully integrated your app with Sitecore Personalize. You sent an event from your app and verified that Sitecore Personalize captures data about your users in real time.
Walkthrough: Integrating using direct HTTP requests
This topic walks you through integrating using direct HTTP requests.
This walkthrough assumes that you:
Have collected the required details about your Sitecore Personalize instance.
Are familiar with the HTTP request-response cycle and with making HTTP requests in the terminal using cURL.
To follow this walkthrough, you'll use a terminal or an API testing tool, for example, Postman. This walkthrough uses cURL in the Git Bash terminal to demonstrate making HTTP requests. In production, you make the HTTP requests in your code base.
This walkthrough describes how to:
Get the browser ID from Sitecore Personalize.
Send your first VIEW event.
Verify that Sitecore Personalize captured your VIEW event.
Get the browser ID from Sitecore Personalize
The first step to integrating is to make an HTTP request to Sitecore Personalize to get the browser ID. You have to include the browser ID in every subsequent request you make to Sitecore Personalize.
To get the browser ID:
In your terminal, make the following HTTP request.
Replace the placeholder values with the required details from your Sitecore Personalize instance.
curl -X GET -g '<stream_api_target_endpoint_PLACEHOLDER>/v1.2/browser/create.json?client_key=<client_key_PLACEHOLDER>'
Example request:
curl -X GET -g 'https://api.boxever.com/v1.2/browser/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe'
The HTTP response body is a JSON object that contains a
ref
key.The
ref
key contains the browser ID."ref" : "a38b230c-11eb-4cf9-8d5d-274e9f344925",
Note down the browser ID. You'll include it in every subsequent request you make to Sitecore Personalize.
Send your first VIEW event
After you have retrieved the browser ID, you send an event as key-value pairs.
To send an event:
Prepare the key-value pairs that describe the VIEW event. In a later step, you pass them to the
message
query parameter in the URL. You must prepare the key-value pairs to be valid in the URL. Make sure that you:Wrap every key and every value in double quotes
""
.Don't add line breaks.
Don't add spaces around keys and around values.
Example key-value pairs:
"browser_id":"a38b230c-11eb-4cf9-8d5d-274e9f344925","channel":"MOBILE_APP","type":"VIEW","language":"EN","currency":"EUR","page":"homepage","pos":"myretailsite/ireland"
Important
Note that the
"browser_id"
key contains the browser ID that you retrieved in a previous step.Every event that you send to Sitecore Personalize must include the browser ID.
In your terminal, make the following HTTP request, passing the key-value pairs to the
message
query parameter.Replace the placeholder values with the required details from your Sitecore Personalize instance.
In the
message
query parameter, replace the placeholder values with event object values specific to your organization.curl -X GET -g '<stream_api_target_endpoint_PLACEHOLDER>/v1.2/event/create.json?client_key=<client_key_PLACEHOLDER>&message={"browser_id":"<browser_id_PLACEHOLDER>","channel":"<channel_PLACEHOLDER>","type":"<type_PLACEHOLDER>","language":"<language_PLACEHOLDER>","currency":"<currency_PLACEHOLDER>","page":"<page_PLACEHOLDER>","pos":"<pos_PLACEHOLDER>"}'
Example request:
curl -X GET -g 'https://api.boxever.com/v1.2/event/create.json?client_key=ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe&message={"browser_id":"a38b230c-11eb-4cf9-8d5d-274e9f344925","channel":"MOBILE_APP","type":"VIEW","language":"EN","currency":"EUR","page":"homepage","pos":"myretailsite/ireland"}'
The event data is sent to Sitecore Personalize.
Verify that Sitecore Personalize captured your VIEW event
After you have sent a VIEW event, you log in to Sitecore Personalize and find the event.
To verify that Sitecore Personalize captured your VIEW event:
In Sitecore Personalize, click Developer center > Event viewer. Paste the copied text into the Search field. A list of events associated with this guest displays. The list contains a VIEW event. This is the event that was triggered in a previous procedure.
Note
If you have both Sitecore CDP and Sitecore Personalize, you can find the data in Guests.
Next steps
You've now now successfully integrated your app with Sitecore Personalize. You made an HTTP request to get the browser ID. Then, using the browser ID, you sent a VIEW event and verified that Sitecore Personalize captures data about your users in real time.
Next, you can:
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 JavaScript Library
If your organization started using Sitecore Personalize before March 2023, your app is probably integrated using the Boxever JavaScript Library. The Boxever JavaScript Library is no longer receiving updates, so we recommend that you upgrade to the Engage JavaScript Library instead.
This walkthrough assumes that you:
Have an app that uses the Boxever JavaScript Library.
Are familiar with HTML, JavaScript, and your web browser's developer tools.
This walkthrough describes how to:
Update the library initializing script.
Update the VIEW event script.
Update the scripts for sending other events.
Update the script for running personalization.
Update the library initializing script
To initialize the Engage JavaScript Library:
Replace your existing script for initializing the Boxever JavaScript Library with the new script.
Your existing script for initializing the Boxever JavaScript Library looks similar to:
Here's the new script for initializing the Engage JavaScript Library:
Replace the placeholder values with the required details from your Sitecore Personalize instance.
Note the following details about the Engage JavaScript Library script:
The
engage
variable is initialized asundefined
.After the
<script>
tag loads, the asynchronousinit()
function loads the Engage JavaScript Library 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 JavaScript Library.
Your existing script using the Boxever JavaScript Library:
Here's the new script for sending a VIEW event using the Engage JavaScript Library. Place this at to the bottom of the s.addEventListener()
function, below the engage = await window.Engage.init(settings);
line:
Replace the placeholder values with event data object values specific to your organization.
Note the following details about the Engage JavaScript Library script:
The event object has different attributes than in the Boxever JavaScript Library.
browser_id
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 JavaScript Library, some event types have their own function.
To send events:
Replace your existing
Boxever.eventCreate()
functions with the applicable function from the following table:
Event type | Function |
---|---|
VIEW | |
IDENTITY | |
|
Update the script for running personalization
In your existing Boxever JavaScript Library script, you're using the Boxever.callFlows()
function to run experiences and experiments.
To run personalization using the Engage JavaScript Library:
Use the
Engage.personalize()
function.
Next steps
You've now successfully upgraded from the Boxever JavaScript Library to the Engage JavaScript Library. You initialized the Engage JavaScript Library, then updated your scripts for sending events.
Next, you can:
Learn more about sending behavioral and transactional data using the Engage JavaScript Library.
Understanding integration details
This topic describes important concepts and details related to integrating with Sitecore Personalize.
Browser ID
The browser ID is a universally unique identifier (UUID) that Sitecore Personalize assigns to every user of your app. It associates sessions, events, and orders with the respective user.
The browser ID in integrations using the Engage JavaScript Library or the Engage SDK
The Engage JavaScript Library and the Engage SDK automatically create the browser ID. Then, the web browser stores the browser ID as a first-party cookie. The cookie is persisted until it expires or gets deleted.
You can use the Engage.getBrowserId()
function to get the browser ID, then find data about the associated user in Sitecore Personalize.
When you send events, the Engage JavaScript Library and the Engage SDK automatically include the browser ID in the event data object.
When you run experiences and experiments without including any optional guest identifier attributes in the personalization data object, the Engage JavaScript Library and the Engage SDK automatically include the browser ID in the personalization data object.
The browser ID in integrations using direct HTTP requests
You have to manually request a browser ID first. To do this, you make a GET request to the Browser API (Stream API type). The response includes the browser ID. In every event that you send to Sitecore Personalize, you have to manually include the browser ID.
The browser ID in Sitecore Personalize
If you know the browser ID for a user of your app, you can use the browser ID to find data about the user in Sitecore Personalize.
Then, Sitecore Personalize lists the guest profile for the user. In the guest profile, you can find session, event, and order data about your user.
Geolocation data
The Engage JavaScript Library and the Engage SDK automatically collect geolocation data about the users of your app. The geolocation data includes city, country, and continent information based on the user's IP address.
Cookies in the Engage SDK
Sitecore Personalize stores cookies in the web browser as first-party cookies. First-party cookies are cookies set by the domain that appears in the web browser's address bar.
The Engage SDK supports setting cookies from the client and from the server.
Client-set cookies
If you can access only the client side of your app, you have to set cookies from the client.
You can set cookies from the client by setting the forceServerCookieMode
attribute to false
in the settings object, then passing the settings object to the Engage.init()
function. For code samples, see Integrating a React app and Integrating a Next app (client-set cookies).
Server-set cookies
If you can access the server side of your app, you can choose to set cookies from the server instead of the client. In that scenario, you create and manage cookies on your web server. Then, the web server sends the cookies to the client app. Finally, the client app stores the cookie in the web browser.
Setting cookies from the server has the following benefits:
Increases security by adding the
httpOnly
attribute to cookies. This helps prevent client-side JavaScript from accessing the cookies and mitigate cross-site scripting (XSS) attacks.Mitigates the impact of Intelligent Tracking Prevention (ITP) on cookies. For example, unlike client-set cookies, server-set cookies don't expire automatically after 7 days.
Using the Engage SDK, you can set cookies from the server by setting the forceServerCookieMode
attribute to true
in the settings object, then passing the settings object to the Engage.init()
function on the client side, and to the Engage.initServer()
function on the server side. For code samples, see Integrating a Next app (server-set cookies).
Sending events using the Engage JavaScript Library or the Engage SDK
Using the Engage JavaScript Library or the Engage SDK, you can collect and send behavioral data to Sitecore Personalize in real time. The behavioral data includes, for example, the user's page views, clicks, searches, and identifiers as they register or log in.
To collect and send behavioral data in real time, you send events to Sitecore Personalize using either client-side tracking or server-side tracking. The Engage JavaScript Library supports client-side tracking. The Engage SDK supports both client-side tracking and server-side tracking.
You can send the following events:
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 JavaScript Library or the Engage SDK
Using the Engage JavaScript Library or the Engage SDK, you can collect and send transactional data to Sitecore Personalize in real time.
You collect and send transactional data in the same way as you collect and send behavioral data, using either client-side tracking or server-side tracking. The Engage JavaScript Library supports client-side tracking. The Engage SDK supports both client-side tracking and server-side tracking.
The transactional data includes orders that the user makes as they interact with your app. You can send an order to Sitecore Personalize in real time using either a single event or multiple events.
Sending orders using a single event
Use this option if your organization's site is tagged to send all order-related data from the confirmation page. You can also use this option if your organization uses an order management system (OMS), or if your organization uses cookies and local storage to capture order details.
To send an order to Sitecore Personalize in real time using a single event, you must use the Engage.event()
function (client-side tracking) or the EngageServer.event()
function (server-side tracking) to send an ORDER_CHECKOUT event.
Sending orders using multiple events
Use this option if the booking flow for your organization's site does not facilitate sending all order-related data from the confirmation page. This way, you can send individual events related to orders when, for example, a user adds a product to their shopping cart, makes a purchase, or empties their shopping cart.
To send an order to Sitecore Personalize in real time using multiple events, you must use the Engage.event()
function (client-side tracking) or the EngageServer.event()
function (server-side tracking) to send the following events in this sequence:
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 Personalize.
Server-side tracking with the Engage SDK
If you can access the server side of your app, you can use the Engage SDK to implement server-side tracking instead of client-side tracking.
Client-side tracking means that you send behavioral and transactional data from the client side of your app directly to Sitecore Personalize.
In contrast, server-side tracking means that you send the data from the client to the server first. Then, you forward the data from the server to Sitecore Personalize.
Benefits of server-side tracking
Compared to client-side tracking, server-side tracking has the following benefits:
Increases data security - you can handle sensitive data on the server without having to expose it on the client side.
Increases data flexibility - on the server, you can extend the data, integrate it with other external systems, or otherwise customize it before forwarding it to Sitecore Personalize.
Prevents ad blockers and web browsers from blocking the tracking code or otherwise manipulating the data.
Improves website performance by reducing the number of network requests to external systems. This improves website speed and ensures that data is captured even on poor network connections.
Considerations before implementing server-side tracking
Before you implement server-side tracking, make sure that your server-side infrastructure is secure, and that you handle data in compliance with privacy regulations.
Implementing server-side tracking
Using the Engage SDK, you can implement server-side tracking by initializing the Engage SDK on the server side of your app, then sending events using the server-side tracking functions.
Queueing events using the Engage JavaScript Library or the Engage SDK
Using the Engage JavaScript Library or the Engage SDK, you can collect events and send them later in one go. This is useful when, for example, you want to conditionally chain different events depending on which actions your user takes.
To collect events, you can use the event queue. The event queue is a first-in, first-out array stored in session storage in the EngageEventQueue
key. You can add any event with a valid payload to the event queue.
Important
The event queue requires that session storage is enabled. Because users can disable session storage, you should use try-catch blocks to handle errors when you're interacting with the event queue.
To interact with the event queue, you can use the following functions:
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 Personalize
After integrating, Sitecore Personalize starts capturing the behavioral and transactional data from your app.
Running personalization
Running interactive full stack experiences and experiments
You can run interactive full stack experiences and experiments by using the Engage.personalize()
function (client-side tracking) or the EngageServer.personalize()
function (server-side tracking).
Running web experiences and web experiments
While you're initializing the Engage JavaScript Library or the Engage SDK, you can decide whether to run web experiences and web experiments in your app. You can run web experiences and web experiments by setting the webPersonalization
attribute to true
in the settings object in the Engage.init()
function, on the client side of your app. This attribute is not available on the server side.
Rerunning web experiences and web experiments
When the Engage functionality first loads in your app with the webPersonalization
attribute set to true
in the settings object, web experiences and web experiments run once. The experiences and experiments don't automatically run again on the same page. This means that you'll need to rerun experiences and experiments in, for example, the following scenarios:
You want to run personalization multiple times on the same page, for example, after the user fills out a form field or clicks a button.
You have a single-page application (SPA), which consists of only one web document, and you want to run personalization when the user navigates between routes.
Using the Engage JavaScript Library and the Engage SDK, you can rerun web experiences and web experiments by using the Engage.triggerExperiences()
function.
Behavioral and transactional data in personalized content
Using the Engage JavaScript Library or the Engage SDK, you can collect and send behavioral and transactional data that occur inside a web experience or a web experiment. To achieve this, you need to call Engage functions inside your web experience or web experiment.
If you integrate using the Engage JavaScript Library, you can call, for example, the Engage.pageView()
function inside your web experience or web experiment.
If you integrate using the Engage SDK, you first need to expose the Engage functions to the window
object. You can expose them by assigning the return value of the Engage.init()
function to a new property on the window
object. For example, you can assign the return value to window.Engage.exposedFunctions
. You can then call, for example, the Engage.exposedFunctions.pageView()
function inside your web experience or web experiment.
Finding the Sitecore Engage version number
After you load the Engage JavaScript Library or initialize the Engage SDK on your website, you can check which version of Sitecore Engage your website is using.
Regardless of how you integrated, the easiest way you can find the Sitecore Engage version number is to inspect the network requests that your website makes. You can do this by opening your web browser's developer tools, then navigating to your website. In the developer tools, on the Network tab, click one of the events you sent. Every event request is called events. In events, the version number is in Headers > Request Headers > x-library-version.

Depending on how you integrated, there are also alternative ways you can find the Sitecore Engage version number.
You can find the version number by opening your web browser's developer tools, then navigating to your website, then doing one of the following:
On the Console tab, log
engage.version
to the console. The version number is returned.In the HTML tree (usually on the Elements tab or Inspector tab), search for
sitecore-engage-v.
. This will find a<script>
tag with 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.
Engage JavaScript Library and Engage SDK reference
Using the Engage JavaScript Library or the Engage SDK is the recommended way to integrate your app with Sitecore Personalize.
This section describes the most commonly used functions and objects, how to troubleshoot common errors, and release notes for the Engage JavaScript Library and the Engage SDK.
Functions
If you integrate with Sitecore Personalize using the Engage JavaScript Library or the Engage SDK, use this reference for creating your functions.
Engage.init(settings)
The asynchronous init()
function initializes the Engage JavaScript Library or the Engage SDK on the client side of your app. Call this function after the window
object is defined and before you call any other Engage functions.
During initialization, the function creates a browser ID and stores it as a cookie in the browser.
Parameters
Parameter | Type | Description |
---|---|---|
object | Details about your Sitecore Personalize 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 JavaScript Library s.addEventListener("load", async () => { const settings = { clientKey: "<client_key_PLACEHOLDER>", targetURL: "<stream_api_target_endpoint_PLACEHOLDER>", pointOfSale: "<point_of_sale_PLACEHOLDER>", cookieDomain: "<cookie_domain_PLACEHOLDER>", cookieExpiryDays: 365, forceServerCookieMode: false, includeUTMParameters: true, webPersonalization: "<boolean_or_object>" }; engage = await window.Engage.init(settings); });
// Initialize the engage variable var engage = undefined; // Create and inject the <script> tag into the HTML var s = document.createElement("script"); s.type = "text/javascript"; s.async = true; s.src = "https://d1mj578wat5n4o.cloudfront.net/sitecore-engage-v.1.3.0.min.js"; var x = document.querySelector("script"); x.parentNode.insertBefore(s, x); // Initialize the Engage JavaScript Library s.addEventListener("load", async () => { const settings = { clientKey: "<client_key_PLACEHOLDER>", targetURL: "<stream_api_target_endpoint_PLACEHOLDER>", pointOfSale: "<point_of_sale_PLACEHOLDER>", cookieDomain: "<cookie_domain_PLACEHOLDER>", cookieExpiryDays: 365, forceServerCookieMode: false, includeUTMParameters: true, webPersonalization: "<boolean_or_object>" }; engage = await window.Engage.init(settings); });
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 Personalize 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 Personalize.
Engage.getGuestId()
The getGuestId()
function returns the guest reference.
Parameters
none
Log the guest reference to the console:
console.log(engage.getGuestId());
// "f7aabbca-1c1b-4fc2-be72-3e16294a4f03"
console.log(engage.getGuestId());
// "f7aabbca-1c1b-4fc2-be72-3e16294a4f03"
Engage.updatePointOfSale(pointOfSale)
The updatePointOfSale()
function updates the value of pointOfSale
that you previously specified in the settings object. Then, every event that you send inside the scope of this function will automatically include the updated point of sale.
Parameters
Parameter | Type | Description |
---|---|---|
| string | The new point of sale. You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize. |
Here's an example of a scenario where an organization uses multiple points of sale. The default point of sale is specified as "myretailsite"
in the settings object. If certain conditions are met, the point of sale is updated to "myretailsite/europe"
. Then, a VIEW event is sent with the new point of sale.
import { init } from "@sitecore/engage"; const loadEngage = async () => { const engage = await init({ // ... pointOfSale: "myretailsite" }); if (region === "europe") { engage.updatePointOfSale("myretailsite/europe"); engage.pageView({ // ... }); }; };
import { init } from "@sitecore/engage"; const loadEngage = async () => { const engage = await init({ // ... pointOfSale: "myretailsite" }); if (region === "europe") { engage.updatePointOfSale("myretailsite/europe"); engage.pageView({ // ... }); }; };
Engage.pageView(eventData[, extensionData])
Note
This is a client-side function used for implementing client-side tracking. If you want to implement server-side tracking instead, use the server-side functions.
The pageView()
function sends a VIEW event. The VIEW event triggers every time your webpage loads. You should send a VIEW event from every webpage that you want to track on your website.
Parameters
Parameter | Type | Description |
---|---|---|
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 Personalize await engage.identity(eventData, extensionData); }; return ( <form onSubmit={handleSubmit}> <label> <span>Email:</span> <input type="text" onChange={handleEmail} value={email} /> </label> <button>Subscribe</button> </form> ) };
import { useState } from "react"; import { engage } from "../engage"; export default function Form() { const [email, setEmail] = useState(""); const handleEmail = (e) => { setEmail(e.target.value); }; const handleSubmit = async (e) => { e.preventDefault(); const eventData = { channel: "WEB", currency: "EUR", pointOfSale: "myretailsite/ireland", language: "EN", page: "home", email, identifiers: [ { id: "123456", provider: "BXLP" } ] }; const extensionData = { customKey: "customValue" }; // Send IDENTITY event to Sitecore Personalize await engage.identity(eventData, extensionData); }; return ( <form onSubmit={handleSubmit}> <label> <span>Email:</span> <input type="text" onChange={handleEmail} value={email} /> </label> <button>Subscribe</button> </form> ) };
Engage.event(type, eventData[, extensionData])
The event()
function sends one of the following:
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 Personalize reserved event names, for example, VIEW, ADD, or CONFIRM, the event becomes a standard event. Sitecore Personalize 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 Personalize 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(); }; };
Engage.personalize(personalizationData[, timeout])
The personalize()
function runs an interactive full stack experience or an interactive full stack experiment that's currently live in Sitecore Personalize. You must call this function with the friendlyId
of the live experience or experiment that you want to run.
Note
Call this function to run a live Interactive full stack experience or a live Interactive full stack experiment only.
Web experiences and web experiments are run by the Engage SDK automatically.
You can find the friendlyId
in Sitecore Personalize, in a live interactive full stack experience or experiment, by clicking Details. The friendlyId
is in Setup Details > ID.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
object | Event and experiment data. | Specify the | |
optional | integer Minimum | The number of milliseconds before the function times out and returns an error. When you use the | For example, set the value to 10000 for the function to time out in 10 seconds. |
Here's an example of how to run an experience or experiment and log it to the console.
import { engage } from "./engage.js"; // ... const handlePersonalization = async () => { const response = await engage.personalize(personalizationData); console.log(response); };
import { engage } from "./engage.js"; // ... const handlePersonalization = async () => { const response = await engage.personalize(personalizationData); console.log(response); };
EngageServer.pageView(eventData, req[, extensionData])
Note
This is a server-side function used for implementing server-side tracking. If you want to implement client-side tracking instead, use the client-side functions.
The pageView()
function sends a VIEW event. The VIEW event triggers every time your webpage loads. You should send a VIEW event from every webpage that you want to track on your website.
Parameters
Parameter | Type | Description |
---|---|---|
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 Personalize reserved event names, for example, VIEW, ADD, or CONFIRM, the event becomes a standard event. Sitecore Personalize 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 Personalize 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;
};
EngageServer.personalize(personalizationData, callback[, timeout])
Note
This is a server-side function used for implementing server-side tracking. If you want to implement client-side tracking instead, use the client-side functions.
The personalize()
function runs an interactive full stack experience or an interactive full stack experiment that's currently live in Sitecore Personalize. You must call this function with the friendlyId
of the live experience or experiment that you want to run.
Note
Call this function to run a live Interactive full stack experience or a live Interactive full stack experiment only.
Web experiences and web experiments are run by the Engage SDK automatically.
You can find the friendlyId
in Sitecore Personalize, in a live interactive full stack experience or experiment, by clicking Details. The friendlyId
is in Setup Details > ID.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
object | Event and experiment data. | Specify the | |
| function | This callback function handles the response. | N/A |
optional | integer Minimum | The number of milliseconds before the function times out and returns an error. When you use the | For example, set the value to 200 for the function to time out in 0.2 seconds. |
Here's an example of how to run an experience or experiment and log it to the console.
export async function middleware(req) { const res = NextResponse.next(); // Load Engage API const engageSettings = { clientKey: "<client_key_PLACEHOLDER>", targetURL: "<stream_api_target_endpoint_PLACEHOLDER>", pointOfSale: "<point_of_sale_PLACEHOLDER>" }; // Personalization data const personalizationData = { channel: "WEB", currency: "EUR", friendlyId: "running_shoes_popup_02", // optional attributes: params: { key: "value" } } const engageServer = await initServer(engageSettings); await engageServer.personalize(personalizationData, (res) => {console.log(res)}, 4000); return res; };
export async function middleware(req) { const res = NextResponse.next(); // Load Engage API const engageSettings = { clientKey: "<client_key_PLACEHOLDER>", targetURL: "<stream_api_target_endpoint_PLACEHOLDER>", pointOfSale: "<point_of_sale_PLACEHOLDER>" }; // Personalization data const personalizationData = { channel: "WEB", currency: "EUR", friendlyId: "running_shoes_popup_02", // optional attributes: params: { key: "value" } } const engageServer = await initServer(engageSettings); await engageServer.personalize(personalizationData, (res) => {console.log(res)}, 4000); return res; };
window.Engage.triggerExperiences()
The triggerExperiences()
function reruns every web experience and web experiment that's live in Sitecore Personalize. This function is particularly useful if you want to run personalization, for example:
In a multi-page application, on the same page in response to user input.
In a single-page application (SPA), when the user navigates between routes.
You can only use this function if you previously set the webPersonalization
attribute to true
in the settings object in the Engage.init()
function, on the client side of your app.
Here's an example of how to use the triggerExperiences()
function to make sure that web experiences and web experiments always run on the /contact
route of a SPA app.
import { init } from "@sitecore/engage"; let engage; const loadEngage = async () => { engage = await init({ // ... webPersonalization: true }); // Make sure web experiences and web experiments always run in SPA apps: if (window.location.pathname.includes("/contact")) { window.Engage.triggerExperiences(); } };
import { init } from "@sitecore/engage"; let engage; const loadEngage = async () => { engage = await init({ // ... webPersonalization: true }); // Make sure web experiences and web experiments always run in SPA apps: if (window.location.pathname.includes("/contact")) { window.Engage.triggerExperiences(); } };
Event data object
Use the event data object to collect behavioral and transactional data about a user's interaction with your app. You can optionally collect custom data using the extension data object. After you create your event data objects, you can send the events to Sitecore Personalize.
Required attributes
At a minimum, every event data object must include the following attributes. Note that event data objects for different event types may require more attributes than listed in this table.
Attribute | Type | Description | Example |
---|---|---|---|
| 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 Personalize. 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 Personalize with UTM parameters included. By default, the VIEW event data object includes UTM parameters. You can exclude UTM parameters from the VIEW event data object by setting the value for includeUTMParameters
to false
in the settings object.
When a VIEW event triggers, the event data includes all the UTM parameters that are in the URL:
{ { ... } "utm_source":"newsletter", "utm_medium":"email", "utm_campaign":"summer_sale", "utm_term":"running shoes" }
{ { ... } "utm_source":"newsletter", "utm_medium":"email", "utm_campaign":"summer_sale", "utm_term":"running shoes" }
IDENTITY event
The event data object for an IDENTITY event must include all the required attributes for event data objects plus the following attributes:
Attribute | Type | Description | Example |
---|---|---|---|
| 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 Personalize, 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 Personalize. This is an optional object that you can specify as the last function argument when you send events. This object accepts a maximum of 50 custom attributes of your choice.
After you send the event, the data in this object becomes available for personalization and decisioning.
When you build this object, use a flat object structure. Sitecore Personalize automatically flattens nested objects and renames the keys as necessary. For example:
Here's an example of how to use the event()
function to send a custom event called myretailsite:CLICKED_POPUP
. eventData
contains all the required attributes for the event data object. extensionData
contains the custom data.
import { engage } from "./engage.js";
// ...
const handleClick = async (e) => {
e.preventDefault();
const eventData = {
channel: "WEB",
currency: "EUR",
pointOfSale: "myretailsite/ireland",
language: "EN",
page: "home"
};
const extensionData = {
customKey: "customValue"
};
await engage.event("myretailsite:CLICKED_POPUP
", eventData, extensionData);
};
import { engage } from "./engage.js";
// ...
const handleClick = async (e) => {
e.preventDefault();
const eventData = {
channel: "WEB",
currency: "EUR",
pointOfSale: "myretailsite/ireland",
language: "EN",
page: "home"
};
const extensionData = {
customKey: "customValue"
};
await engage.event("myretailsite:CLICKED_POPUP
", eventData, extensionData);
};
Personalization data object
Use the personalization data object to collect identifying data about a user, and the friendlyID
of an interactive full stack experience or an interactive full stack experiment that you want to run for the user. You then send the object to Sitecore Personalize, and Sitecore Personalize runs the experience or experiment.
After you create this object, you can send it using the Engage.personalize()
function.
Required attributes
At a minimum, every personalization data object must include the following attributes:
Attribute | Type | Description | Example |
---|---|---|---|
| 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 Personalize. If you did not specify If you specified |
|
| string | The ID of a live interactive full stack experience or live interactive full stack experiment that you want to run. |
|
Optional attributes
A personalization 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 |
|
| object | An object of your choice. Use a flat object structure. Sitecore Personalize automatically flattens nested objects and renames the keys as necessary. For example: |
|
Optional guest identifier attributes
A personalization data object can optionally include no more than one of the following guest identifier attributes. If the personalization data object doesn't contain any of these attributes, the browser ID becomes the guest identifier.
Attribute | Type | Description | Example |
---|---|---|---|
| string (lowercase recommended) | The email address of the guest. |
|
| object | The identity identifiers that are used to identify the users of your app. | identifier: { "id": "123456", "provider": "BXLP" } |
The identifier
object:
Attribute | Type | Description | Example | Required/optional |
---|---|---|---|---|
| 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 Personalize, that provided the unique guest identifier. |
| Required |
Here's an example of a personalization data object that doesn't contain the email
attribute or the identifier
attribute to identify the guest. In this case, the browser ID is the guest identifier. This personalization data object also contains an optional custom object.
const personalization = { channel: "WEB", currency: "EUR", pointOfSale: "myretailsite/ireland", friendlyId: "running_shoes_popup_02", // optional attributes: params: { key: "value" } }
const personalization = { channel: "WEB", currency: "EUR", pointOfSale: "myretailsite/ireland", friendlyId: "running_shoes_popup_02", // optional attributes: params: { key: "value" } }
Here's an example of a personalization data object that uses the email
attribute as the guest identifier.
const personalization = { channel: "WEB", currency: "EUR", pointOfSale: "myretailsite/ireland", friendlyId: "running_shoes_popup_02", // guest identifier: email: "jane.doe@myretailsite.com" }
const personalization = { channel: "WEB", currency: "EUR", pointOfSale: "myretailsite/ireland", friendlyId: "running_shoes_popup_02", // guest identifier: email: "jane.doe@myretailsite.com" }
Here's an example of a personalization data object that uses the identifiers
attribute as the guest identifier.
const personalization = { channel: "WEB", currency: "EUR", pointOfSale: "myretailsite/ireland", friendlyId: "running_shoes_popup_02", // guest identifier: identifier: { id: "123456", provider: "BXLP" } }
const personalization = { channel: "WEB", currency: "EUR", pointOfSale: "myretailsite/ireland", friendlyId: "running_shoes_popup_02", // guest identifier: identifier: { id: "123456", provider: "BXLP" } }
Settings object
Use the settings object to initialize the Engage JavaScript Library or the Engage SDK. In the settings object, you include details about your Sitecore Personalize instance.
The Engage SDK supports setting cookies from the client and from the server.
To set cookies from the client, you must set the
forceServerCookieMode
attribute 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 Personalize 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 Personalize. 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 JavaScript Library or the Engage SDK.
Errors in the console
400 Bad Request when running Engage.personalize()
This error occurs when you're trying to return an experiment or experience for a user of your app using an email address or other identifiers that don't exist in Sitecore Personalize. To fix the error, in the personalization data object, specify identifiers that exist in Sitecore Personalize.
401 Unauthorized
This error occurs when the value for the clientKey
attribute is incorrect. To fix the error, set the value to the correct client key.
404 Not Found
This error occurs in the following cases:
The browser ID was not stored as a cookie in the web browser. This happens when, for example, a user of your app rejects cookies or the web browser is blocking cookies. To send events and call personalization, the browser ID must be stored as a cookie in the web browser.
The value for the
targetURL
attribute is the wrong URL from the available URLs for the Stream API. To fix the error, set the value to the correct Stream API target endpoint.
Cookie has been rejected for invalid domain
This error occurs when the value for the cookieDomain
is incorrect. To fix the error, set the value to the correct cookie domain.
Cross-origin request blocked
This error occurs when the value for the targetURL
attribute is different than the available URLs for the Stream API. To fix the error, set the value to the correct Stream API target endpoint.
IE errors
IE
errors are related to initializing the Engage SDK.
Code | Description | Note |
---|---|---|
| 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. |
|
| See examples of correctly formatted data. |
|
| Set the value to the name of your point of sale. |
Events not appearing in Sitecore Personalize
This issue occurs if you sent an event to Sitecore Personalize and your web browser console contains no errors, but the value for the pointOfSale
attribute is incorrect.
To fix the error:
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 Personalize
This issue occurs if an ADD, CONFIRM, or CHECKOUT event is set up incorrectly.
To fix the error:
Make sure that the event data objects for the ADD, CONFIRM, and CHECKOUT events are correctly formatted.
Make sure to send the events in the correct sequence.
For each item ID included in an object in the
product
array of the CONFIRM event data object, there must be a preceding ADD event data object where the product item ID is specified inproduct.item_id
.See examples.
Release notes
The following table contains Engage JavaScript Library and Engage SDK release notes.
Version | Release notes |
---|---|
1.3.0 | Adds the ability to check which version of Sitecore Engage your app is using. |
1.2.0 | Adds the ability to let the |
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.
If your application uses the Boxever JavaScript Library, we recommend that you upgrade to the Engage JavaScript Library to get future updates and enhancements.
If you are a new customer, use the Engage JavaScript Library or the Engage SDK.
This section describes the most commonly used functions and objects, how to troubleshoot common errors, and release notes for the Boxever JavaScript Library.
Reference
This topic describes in detail the most commonly used methods and objects in the Boxever JavaScript Library.
The following methods are used in production:
Boxever.eventCreate()
, to send data to Sitecore Personalize.Boxever.callFlows()
, to get data from Sitecore Personalize.
Boxever.eventCreate(event, callback, format)
The eventCreate()
function sends an event to Sitecore Personalize. An event is all the data about a user's interaction with your application. Call this function as part of the anonymous function that you add to the _boxeverq
array.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
object | All the event data. | Specify the browser ID in this object. Every event that you send to Sitecore Personalize must include the browser ID. | |
| 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 Personalize. The _boxeverq
array receives an anonymous function. The anonymous function contains a VIEW event object. The eventCreate()
function receives the VIEW event object and sends the event data to Sitecore Personalize.
Boxever.callFlows(flow, callback)
The callFlows()
function runs an Interactive Full Stack Experience or an Interactive Full Stack Experiment that is currently live in Sitecore Personalize. You must call this function with the friendlyId
of the live experience or experiment that you want to run.
Note
Call this function to run a live Interactive Full Stack Experience or a live Interactive Full Stack Experiment only. Other types of experiences and experiments (Web, Triggered Full Stack) are run by the Boxever JavaScript Library automatically.
You can find the friendlyId
in Sitecore Personalize, in a live interactive full stack experience or experiment, by clicking Details. The friendlyId
is in Setup Details > ID.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
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 Personalize using the Boxever JavaScript Library.
Boxever.addUTMParams(event)
The addUTMParams()
function adds every UTM parameter from the URL of the current webpage to the event object.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
object | All the event data. | N/A |
Return value
none
Example
Here's an example of UTM parameters:
https://myretailsite.com?utm_source=newsletter&utm_medium=email&utm_campaign=summer_sale&utm_term=running+shoes
By default, the event object does not include UTM parameters. To add the UTM parameters to the event object, pass the event object to the addUTMParams()
function:
The event data that is sent to Sitecore Personalize now includes all UTM parameters:
Boxever.browserCreate(object, callback, format)
The browserCreate()
function creates a browser ID and a guest reference.
Important
The Boxever JavaScript Library calls this function automatically when no browser ID is found in the cookies or in local storage. We recommend that you do not call this function. To create a browser ID or guest reference manually, use the reset()
function instead.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
| object | 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 Personalize.
The guest reference is in the customer.ref
key of the parameter that is passed to the callback function.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
| 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 Personalize. Call this function after an IDENTITY event triggers. This updates the cookie in the browser to match the bucket number in Sitecore Personalize.
Note
This function is specific to Web Experiences and Web Experiments in Sitecore Personalize, and it is only available if you specified web_flow_target
when you integrated with Sitecore Personalize using the Boxever JavaScript Library.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
optional | function | This callback function handles the response. | N/A |
Return value
undefined
Example
This example describes how to test that the getBucketNumber()
function updates the bucket number cookie in the browser.
First, you get the latest bucket number from Sitecore Personalize using the getBucketNumber()
function and log the bucket number cookie to the console using the getCookie()
function.
Then, you call the reset()
function to reset the guest reference:
Sitecore Personalize creates a new guest reference and assigns a bucket number to this guest. But the bucket number cookie in the browser stays unchanged.
To update the cookie in the browser, you get the latest bucket number from Sitecore Personalize again using the getBucketNumber()
function. Then, you log the bucket number cookie to the console using the getCookie()
function:
The bucket number cookie is now different.
Boxever.getClientKey()
The getClientKey()
function returns the client key.
Parameters
none
Return value
string
Example
Log the client key to the console:
Boxever.getCookie(cookieName)
The getCookie()
functions receives a cookie name and returns the corresponding cookie value.
Note
This function only works for cookies set by the Boxever JavaScript Library and for cookies set using the setCookie()
function.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
| string or number | The name of the cookie. | N/A |
Return value
string
Example
Call the getCookie()
function:
Boxever.getID()
The getID()
function returns the browser ID.
Every event that you send to Sitecore Personalize must include the browser ID.
Use this function in every event object you create and send to Sitecore Personalize. See eventCreate()
.
Parameters
none
Return value
string
Example
Log the browser ID to the console:
Boxever.reset()
The reset()
function reinitializes the Boxever JavaScript Library. During reinitialization, the function:
Clears the event queue.
Deletes the browser ID and the guest reference.
Reloads the Boxever JavaScript Library. During loading, the Boxever JavaScript Library creates a browser ID and a guest reference.
Parameters
none
Return value
undefined
Example
This example describes how to test that the reset()
function deletes, then creates a new browser ID.
Boxever.setCookie(cookieName, cookieValue[, expiresIn])
The setCookie()
function creates a cookie in the browser.
Parameters
Parameter | Type | Description | Note |
---|---|---|---|
| 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.
If your application uses the Boxever JavaScript Library, we recommend that you upgrade to the Engage JavaScript Library to get future updates and enhancements.
If you are a new customer, use the Engage JavaScript Library or the Engage SDK.
If you integrate with Sitecore Personalize using the Boxever JavaScript Library or direct HTTP requests, use this event object to collect all the event data about a user's interaction with your application. You then send the event to Sitecore Personalize.
Required attributes
At a minimum, every event data object must include the following attributes. Note that event data objects for different event types may require more attributes than listed in this table.
Attribute | Type | Description | Example |
---|---|---|---|
| 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 Personalize standard event, for example, VIEW or IDENTITY, set the value to a Sitecore Personalize reserved event name. To send a custom event, set the value to a custom event name of your choice. The custom event name must be different than reserved event namesSitecore Personalize. Sitecore Personalize reserved event names: |
|
| 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 Personalize. |
|
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 Personalize, 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 Personalize reserved event names.
You can add custom attributes of your choice.
Example
This example describes an event object for a custom event in an integration that uses the Boxever JavaScript Library. The browser_id
is set to the value that the Boxever.getID()
function returns.
In the type
attribute of the event, the custom event name is specified as myretailsite:CLICKED_POPUP
. The event contains the custom attributes clickedPopup
and timeBetweenPopupAndClick
.
Event object for SEARCH events
The event object for a SEARCH event must include all the required attributes for event objects plus the following attributes:
Attribute | Type | Description | Example | Required/optional |
---|---|---|---|---|
| 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 Engage JavaScript Library to get future updates and enhancements.
If you integrate with Sitecore Personalize using the Boxever JavaScript Library or direct HTTP requests, use the flow object to collect identifying data about a user, and the friendlyID
of an Interactive Full Stack Experience or an Interactive Full Stack Experiment that you want to run for the user. You then send the object to Sitecore Personalize, and Sitecore Personalize runs the experience or experiment.
Required attributes for flow objects
At a minimum, every flow object must include the following attributes plus one guest identifier attribute:
Attribute | Type | Description | Example | Required/optional |
---|---|---|---|---|
| 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 Personalize. |
| 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 Personalize, 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 Personalize
If you sent an event to Sitecore Personalize and your web browser console contains no errors, this issue occurs if the value for the pointOfSale
key is incorrect.
To fix the error:
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 Personalize using direct HTTP requests, use this reference for formatting your requests. Every parameter and attribute is required unless marked as optional.
Base URL
The base URL is determined by the environment of your Sitecore Personalize instance.
To find the environment, in Sitecore Personalize, on the navigation pane, click > 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 Personalize 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 Personalize using the Browser API (Stream API type). In the response, the ref
key contains the browser ID.
You must include the browser ID in every follow-up request that you make to Sitecore Personalize.
Parameters
Parameter | Type | Description | Example |
---|---|---|---|
| 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 JavaScript Library or the Engage SDK. Using the Engage JavaScript Library or the Engage SDK, you have to format and send your event data differently than described in this section. See Sending events.
GET /v1.2/event/create.json?client_key=client_key&message=event
To send events to Sitecore Personalize using direct HTTP requests, for example, a VIEW event, make GET
requests using the Event API (Stream API type). Pass the event object in the message
parameter. Make sure to format the event object correctly and to include all the required attributes.
Using direct HTTP requests, you can send the following events:
Parameters
Parameter | Type | Description | Example |
---|---|---|---|
| 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 Personalize standard event, for example, VIEW or IDENTITY, set the value to a Sitecore Personalize reserved event name. To send a custom event, set the value to a custom event name of your choice. The custom event name must be different than Sitecore Personalize reserved event names. Sitecore Personalize reserved event names: |
|
| 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 Personalize. |
|
| 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 Personalize 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 Personalize. | 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 Personalize. | 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 Personalize. | 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 Personalize ignores any products or contacts that have been passed to Sitecore Personalize during the browser session.
The CLEAR_CART event is typically sent when a guest performs a new search. This removes all products and contacts from the cart and ensures that Sitecore Personalize does not send an abandoned cart email message to the guest.
2.0 data model
You can send a CLEAR_CART event to ensure that Sitecore Personalize ignores any products, consumers, or contacts that have been passed to Sitecore Personalize during the browser session.
The CLEAR_CART event is typically sent when a guest performs a new search. This removes all products, consumers, and contacts from the cart and ensures that Sitecore Personalize does not send an abandoned cart email message to the guest.
{ "channel": "MOBILE_APP", "type": "VIEW", "language": "EN", "currency": "EUR", "page": "search results page", "pos": "myretailsite/ireland", "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925" }
{ "channel": "MOBILE_APP", "type": "VIEW", "language": "EN", "currency": "EUR", "page": "search results page", "pos": "spinair.com/france", "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925" }
Custom event
A custom event is unique to your organization. For example, most retail sites have an ADD
event that captures when a guest clicks the add button. However, you might want to capture, for example, how many times a guest adds items to a wish list, and for this, there is no standard event in Sitecore Personalize. To do this, you can send a custom event, for example, ADD_TO_WISHLIST
.
You can track how often a custom event is raised by creating a goal for an experiment in Sitecore Personalize. You can also use the raising of the custom event as the basis for declaring a winner in your experiment.
Notice
You send a custom event in the same way that you send a standard event. You must be consistent with the name of the custom event you send and you must not use the name of a standard event.
You can also add a maximum of 50 custom attributes of your choice.
To send a custom event, use the following required attributes:
Attribute | Type | Description | Example |
---|---|---|---|
| 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 Personalize reserved event names. | You must not set the value to any of the Sitecore Personalize 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 Personalize provides different options for sending orders to Sitecore Personalize. The available options depend on, for example, the frequency of order submission, and whether orders are submitted in real-time, offline, or synchronously.
Sending orders using a single event
You can use Sitecore Personalize to submit orders in real time to Sitecore Personalize. Use this option to submit orders using a single event if your organization's site is tagged to send all order-related data from the confirmation page. You can also use this option if your organization uses an order management system (OMS), or if your organization uses cookies and local storage to capture order details.
2.1 data model
To submit an order to Sitecore Personalize in real time, you must send an ORDER_CHECKOUT event.
2.0 data model
Sending orders using multiple events
You can use Sitecore Personalize to assemble orders in real-time if the booking flow for your organization's site does not facilitate sending all order-related data from the confirmation page. For example, your site's confirmation page might not be tagged to capture and send contact information so you would need to send the ADD_CONTACTS
event from a different web page.
2.1 data model
To submit an order to Sitecore Personalize in real time, you must send the following events in this sequence:
2.0 data model
To submit an order to Sitecore Personalize in real time, you must send the following events in this sequence:
Cart abandonment
2.1 data model
You can to track items added to an online cart using the ADD event. If items have been added to the cart, and the stream session closes without an order, then the stream session cartType
is set to ABANDONED
.
Sitecore Personalize enables you to configure an experience to re-engage with the guest and recover the contents of the abandoned cart, for example, to send the guest an email message with the cart contents. The guest must be identified in order for this to work.
The following steps result in an abandoned cart, which triggers an abandoned cart email message:
A guest adds an item to their cart.
An ADD event is sent to Sitecore Personalize.
The guest's session closes manually, by timing out, or by network latency.
Sitecore Personalize 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 Personalize:
A guest adds an item to their cart.
An ADD event is sent to Sitecore Personalize.
The guest removes the item or items from their cart.
A CLEAR_CART event is sent to Sitecore Personalize.
The guest's session closes manually, by timing out, or by network latency.
Sitecore Personalize 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 Personalize
If you sent an event to Sitecore Personalize and the HTTP response has the 201 Created
status code, this issue occurs if the value for the pos
key is incorrect.
To fix the error:
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.
Personalize API Flow execution
You can use the Personalize REST API flow execution service to run a flow for an experiment or experience. You can do this over any web-based or mobile application, so you can personalize dynamic offers or content in real-time. For example, you can nudge the guest onto the next page or encourage them to add a product to their cart or order.
Characteristics of the flow execution service:
Facilitates personalization in experiences and experiments, including interactive and web
Invokes real-time responses
Supports using decision models in interactive experiments to return the next best offer or action
You can send a flow execution request using either the browserId
, email
, or identifiers
attribute. This flexibility is particularly useful when interacting with guests who have never been identified online and do not have a browserId
attribute. You can use the email
or identifiers
attribute to execute a flow that uses a decision model to return the next best offer or action.
You can also send a flow execution request for an experiment or experience when you want to send the output of the decision model in real-time to an external system such as a marketing cloud. The browserId
attribute is not relevant or captured by this type of external system, so we recommend using the email
or identifiers
attribute to execute the flow.
The following table describes flow execution model attributes:
Attribute | Type | Description | Example(s) |
---|---|---|---|
| string | The client key retrieved from Sitecore Personalize. |
|
| string (uppercase) | The channel captured on each page the guest visited. |
|
| string (2 letter ISO 639 language code) | The language captured on each page the guest visited. |
|
| 3 letter ISO 4217 | Your organization’s currency code. |
|
| string (predefined by your organization) | The point of sale used. |
|
| string | The ID of a browser generated by Sitecore Personalize. |
|
| string | The guest's email address. |
|
| JSON object | The unique identifiers of the guest. | N/A |
| JSON object | The parameters returned from the visitor's current URL. | N/A |
The following table describes identifiers
object attributes:
Attribute | Description | Type | Example(s) |
---|---|---|---|
| The identifier provider. | string |
|
| The identifier identification. | string |
|
The following table describes params
object attributes:
Attribute | Description | Type | Example(s) |
---|---|---|---|
| The UTM campaign parameter included in the visitor's current URL. | string |
|
| The UTM source included in the visitor's current URL. | string |
|
| The UTM medium included in the visitor's current URL. | string |
|
| The UTM content included in the visitor's current URL. | string |
|
The friendlyID
You can programmatically run experiments and experiences using the friendlyID
attribute. When you create an experiment or experience, Sitecore Personalize automatically creates an ID when you name the experiment or experience. For example, if you name an experiment Product Recommender, Sitecore Personalize automatically generates an ID named product_recommender
.
In some organizations there might be several variations of an experiment named Product Recommender that have different page targets, audience filters, or other conditions that must be met in order for the experiment to run.
To use this same example, users might intentionally delete some of the experiments named Product Recommender after the marketing campaign is retired. This can often happen across regions. To support referential integrity, Sitecore Personalize automatically appends a numeral to the value of the friendlyID
attribute if the name of the experiment you create is identical to any names of deleted experiments. For example, Sitecore Personalize automatically appends a numeral 2 so the friendlyID
attribute value is product_recommender_2
.
To apply fuzzy matching so that Sitecore Personalize executes the first lexicographical match of the friendlyId
, you pass in product_recommender*
as the value for the friendlyID
attribute. You can use an asterix to apply lexicographical order and execute the first live experment that matches and passes any other conditions such as page targeting and real-time audience filters.
Call the Personalize API
POST /v2/callFlows
Runs an interactive experiment or web experiment over any web-based or mobile application.
You must include one of the following attributes: browserId
or email
or identifiers
. Optionally, you can include custom fields using the params
object.
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey":"abBah8aelipaPeebae7roox2tiexoSee", "channel":"WEB", "language":"en", "currencyCode":"EUR", "pointOfSale":"retailsite.com", "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925", "params":{ "utm":{ "campaign":"summer_sale", "source":"newsletter", "medium":"email", "content":"running shoes" }, "friendlyId":"home_page_banner" } }
Run an experiment or experience using browserId
:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey": "abBah8aelipaPeebae7roox2tiexoSee", "channel": "WEB", "language": "en", "currencyCode": "EUR", "pointOfSale": "myretailsite/ireland", "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925", "friendlyId": "home_page_banner" }'
Run an experiment or experience using email
:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey": "abBah8aelipaPeebae7roox2tiexoSee", "channel": "WEB", "language": "en", "currencyCode": "EUR", "pointOfSale": "myretailsite/ireland", "email": "jane.doe@myretailsite.com", "friendlyId": "home_page_banner" }'
Run an experiment or experience using identifiers
:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey": "abBah8aelipaPeebae7roox2tiexoSee", "channel": "WEB", "language": "en", "currencyCode": "EUR", "pointOfSale": "myretailsite/ireland", "identifiers":{ "id":"123456", "provider":"BXLP" }, "friendlyId": "home_page_banner" }'
Include custom fields:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey": "abBah8aelipaPeebae7roox2tiexoSee", "channel": "WEB", "language": "en", "currencyCode": "EUR", "pointOfSale": "retailsite.com", "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925", "params":{ "loggedInState":"loggedIn", "someKey":"someValue" }, "friendlyId": "home_page_banner" }'
Include UTM parameters in the params.utm
object:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey":"abBah8aelipaPeebae7roox2tiexoSee", "channel":"WEB", "language":"en", "currencyCode":"EUR", "pointOfSale":"retailsite.com", "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925", "params":{ "utm":{ "campaign":"summer_sale", "source":"newsletter", "medium":"email", "content":"running shoes" }, "friendlyId":"home_page_banner" } }
Run an experiment or experience using browserID
:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey": "abBah8aelipaPeebae7roox2tiexoSee", "channel": "WEB", "language": "en", "currencyCode": "EUR", "pointOfSale": "myretailsite/ireland", "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925", "friendlyId": "home_page_banner" }'
Run an experiment or experience using email
:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey": "abBah8aelipaPeebae7roox2tiexoSee", "channel": "WEB", "language": "en", "currencyCode": "EUR", "pointOfSale": "myretailsite/ireland", "email": "jane.doe@myretailsite.com", "friendlyId": "home_page_banner" }'
Run an experiment or experience using identifiers
:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey": "abBah8aelipaPeebae7roox2tiexoSee", "channel": "WEB", "language": "en", "currencyCode": "EUR", "pointOfSale": "myretailsite/ireland", "identifiers":{ "id":"123456", "provider":"BXLP" }, "friendlyId": "home_page_banner" }'
Include custom fields:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey": "abBah8aelipaPeebae7roox2tiexoSee", "channel": "WEB", "language": "en", "currencyCode": "EUR", "pointOfSale": "retailsite.com", "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925", "params":{ "loggedInState":"loggedIn", "someKey":"someValue" }, "friendlyId": "home_page_banner" }'
Include UTM parameters in the params.utm
object:
curl -X POST '<baseURL>/v2/callFlows' \ -H 'Accept: application/json' \ --data-raw ' { "clientKey":"abBah8aelipaPeebae7roox2tiexoSee", "channel":"WEB", "language":"en", "currencyCode":"EUR", "pointOfSale":"retailsite.com", "browserId": "a38b230c-11eb-4cf9-8d5d-274e9f344925", "params":{ "utm":{ "campaign":"summer_sale", "source":"newsletter", "medium":"email", "content":"running shoes" }, "friendlyId":"home_page_banner" } }
[ { "trackingUrl": "<apiEndpoint>/v3/trackers/eyJjaGFubmVsIj", "Name": "Ancillary bundle", "imageURLForTesting": "https://png.icons8.com/ios/50/000000/cardboard-box.png" }, { "trackingUrl": "<apiEndpoint>/v3/trackers/eyJjaGFubmVsIj", "Name": "Ancillary seat", "imageURLForTesting": "https://png.icons8.com/dotty/50/000000/flight-seat.png" }, { "trackingUrl": "<apiEndpoint>/v3/trackers/eyJjaGFubmVsIj", "Name": "Ancillary bag", "imageURLForTesting": "https://png.icons8.com/metro/50/000000/suitcase.png", "nonDependent": "false" }, { "trackingUrl": "<apiEndpoint>/v3/trackers/eyJjaGFubmVsIj", "Name": "Ancillary insurance", "imageURLForTesting": "https://png.icons8.com/ios/50/000000/umbrella.png", "nonDependent": "false" } ]