Objects

Settings object

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

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

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

The settings object includes the following attributes:

Attribute	Type	Description	Example	Required/optional
`clientKey`	string	Your client key.	`"ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe"`	Required
`targetURL`	string	Your Stream API target endpoint. The value depends on the location of your Sitecore Personalize server.	Must be one of: `"https://api-engage-ap.sitecorecloud.io"` `"https://api-engage-eu.sitecorecloud.io"` `"https://api-engage-jpe.sitecorecloud.io"` `"https://api-engage-us.sitecorecloud.io"`	Required
`includeUTMParameters`	boolean	Specify whether to add every UTM parameter from the URL of the current webpage to the event object. The default is `true`. If `true`, UTM parameters are added to the VIEW event object.	`true` or `false`	Optional
`cookieDomain`	string	Your cookie domain. The default is what the browser sets.	`".myretailsite.com"` `".beta.myretailsite.com"` `"localhost"`	Optional
`cookieExpiryDays`	integer	The number of days before the cookie expires. If you don't specify this value, the cookie expires according to the `Max-Age` that the browser sets.	For example, set the value to `1` for the cookie to expire in 1 day.	Optional
`cookiePath`	string	A URL path that must exist in the requested URL in order to send the cookie.	`N/A`	Optional
`forceServerCookieMode`	boolean	Specify whether to set cookies from the client or from the server. If you can access the server side of your app, you can choose to set cookies from the server instead of the client. To set cookies from the server, set the value to `true` on both the server and the client side. The default is `false`.	`true` or `false`	Optional
`webPersonalization`	boolean or object	On the client side, specify whether you want to run personalization with Sitecore Personalize. This attribute is not available on the server side. If you don't specify this attribute on the client side, or if you specify it and set the value to `false`, personalization will not be available. If you set the value to `true` or to an object, you must also specify the `pointOfSale`. If you set the value to `true`, a web personalization script will load in your app with `async` but without `defer`. You can customize the loading of the script by setting the value to an object. In the object: Customize `async` and `defer` using `asyncScriptLoading` and `deferScriptLoading`, respectively. For these attributes, set boolean values. Use the `baseURLOverride` attribute to load the web personalization script from a custom URL. If your Stream API target endpoint is in JP Region, set `baseURLOverride` to: `"https://d2ez8k04aaol9g.cloudfront.net"` Alternatively, if you received a custom URL from Sitecore to load the web personalization script, set `baseURLOverride` to that URL. The default is `false`.	Enable web personalization: `true` Load the script without `async`: `{ asyncScriptLoading: false }` Load the script without `async` but with `defer`: `{ asyncScriptLoading: false, deferScriptLoading: true }` If your Stream API target endpoint is in JP Region: `{ baseURLOverride: "https://d2ez8k04aaol9g.cloudfront.net" }` Load the script using a custom URL: `{ baseURLOverride: "https://..." }`	Optional on the client side. Not available on the server side.
`pointOfSale`	string	The name of the point of sale where the interaction with your brand takes place. If you specified the `webPersonalization` attribute on the client side and set the value to `true` or to an object, you must specify `pointOfSale`. You must set this value to the name of a point of sale that exists in your instance of Sitecore Personalize. If you don't specify `pointOfSale` in the settings object, you must specify it in every event data objectand in the personalization data object.	`"myretailsite/ireland"`	Required if you specified the `webPersonalization` attribute. Optional otherwise.

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

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

const engageSettings = {
  clientKey: "<client_key_PLACEHOLDER>",
  targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
  pointOfSale: "<point_of_sale_PLACEHOLDER>",
  cookieDomain: "<cookie_domain_PLACEHOLDER>",
  cookieExpiryDays: 365,
  forceServerCookieMode: false,
  webPersonalization: false /* boolean or object. Default: false */
};

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

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