@sitecore-cloudsdk/personalize/browser

Version: 0.3

The browser module provides the following functions to run Sitecore Personalize personalizations from the browser side:

Function	Description
`init`	Initializes the module.
`personalize`	Runs interactive experiences and interactive experiments that are live in Sitecore Personalize.

Note

To run Sitecore Personalize personalization in your JSS Next.js app, you need either XM Cloud Plus, or both XM Cloud and Sitecore Personalize.

init(settings)

This asynchronous function initializes the module. You must run this function before you can run any other functions in the module.

Parameters

Parameter	Type	Description	Required/optional
`settings`	settings object	Details about your XM Cloud instance and cookie settings.	Required

settings

Attribute	Type	Description	Example	Required/optional
`sitecoreEdgeContextId`	string (UUID)	Context ID. Accessible and stored as an environment variable in your app.	`"3axQRoRznWUqHR8B2RSbdo"`	Required
`siteName`	string	The name of the site. Accessible and stored as an environment variable in your app.	`"myRetailSite"`	Required
`enableBrowserCookie`	boolean	Flag to set cookies from the browser side. The default is `false`. If you're using both the `browser` and the `server` modules of this package, set the value for either `enableBrowserCookie` or `enableServerCookie` to `true`, and set the value for the other attribute to `false`.	`true` or `false`	Optional
`cookieDomain`	string	Your cookie domain. The cookie domain is the top-level domain of your app. The cookie domain ensures that the Cloud SDK stores cookies in the web browser as first-party cookies. The default is your domain. You must set the same value for this attribute in every Cloud SDK module you initialize.	`".myretailsite.com"` `".beta.myretailsite.com"` `"localhost"`	Optional
`cookieExpiryDays`	integer	The number of days before the cookie expires. If you don't set a value, the cookie expires according to the `Max-Age` that the browser sets. You must set the same value for this attribute in every Cloud SDK module you initialize.	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. The default is `"/"`. You must set the same value for this attribute in every Cloud SDK module you initialize.	`"/"`	Optional

Code examples

JSS Next.js

Here's an example [[...path]].tsx script showing how to initialize the module:

RequestResponse

import { useEffect } from "react";
import { init } from "@sitecore-cloudsdk/personalize/browser";
// ...

const SitecorePage = ({
  notFound,
  componentProps,
  layoutData,
  headLinks,
}: SitecorePageProps): JSX.Element => {
  // ...

  // Initialize the module ->
  const initPersonalize = async () => {
    await init({
      sitecoreEdgeContextId: "<YOUR_CONTEXT_ID>",
      siteName: "<YOUR_SITE_NAME>",
      enableBrowserCookie: true,
    });

    console.log("Initialized the personalize/browser module.");
  };

  initPersonalize();
  // <- Initialize the module
  // ...
};

personalize(personalizationData)

This asynchronous function runs interactive experiences and experiments that are live in Sitecore Personalize.

This function automatically captures UTM parameters from the URL of the webpage where the function runs.

Parameters

Parameter	Type	Description	Required/optional
`personalizationData`	personalizationData object	Event and experiment data. You can include guest identifier attributes in this object to run personalization for a specific guest.	Required

Parameter

Type

Description

Required/optional

personalizationData

personalizationData object

Event and experiment data.

You can include guest identifier attributes in this object to run personalization for a specific guest.

Required

personalizationData

Attribute	Type	Description	Example	Required/optional
`channel`	string (uppercase)	The touchpoint where the user interacts with your brand. For example, for webpages, the channel is `"WEB"`. For mobile app screens, the channel is `"MOBILE_APP"`.	Must be one of: `"AIRPORT_KIOSK"` `"BRANCH"` `"CALL_CENTER"` `"EMAIL"` `"GDS"` `"KIOSK"` `"MOBILE_APP"` `"MOBILE_WEB"` `"SMS"` `"OFFLINE"` `"OTA"` `"OTHER"` `"WEB"`	Required
`currency`	string (uppercase ISO 4217)	The alphabetic currency code of the currency the user is using in your app. For example, if the user selects Australian dollars as the currency on your website, the currency is `"AUD"`.	`"EUR"` `"GBP"` `"USD"`	Required
`friendlyId`	string	The unique identifier of a live interactive experience or live interactive experiment that you want to run. To find the friendly ID in Sitecore Personalize, click the live experience or experiment you want to work with, then click Summary. The friendly ID is on the Details pane.	`"running_shoes_popup_02"`	Required
`language`	string (uppercase ISO 639-1)	The language the user is using your app in. For example, if the user selects the Japanese language on your website, the language is `"JA"`. The default is `"EN"`.	`"DE"` `"EN"` `"FR"`	Optional
`email`	string (lowercase recommended)	The email address of the guest.	`"[email protected]"`	Optional
`identifier`	object	The identifiers that are used to identify the users of your app.	RequestResponse `identifier: { "id": "123456", "provider": "BXLP" }`	Optional
`geo`	object	The site visitor's geolocation data. In JSS Next.js apps, leave unset. JSS Next.js apps use `geo` internally to automatically capture geolocation data.	`geo: { city: "Dublin", country: "IE", region: "Leinster" }`	Optional
`params`	object	An object of your choice. If the URL of the webpage where this function runs contains UTM parameters, those parameters are automatically captured in `params.utm`. You can override the automatically captured UTM parameters by specifying values manually in `params.utm`.	`params: { key: "value" }`	Optional
`pageVariantIds`	`string[]`	A list of IDs of personalized page variants. Ensures that the correct variants are rendered for personalization. If unset or an empty array, this property will not be part of the payload.	`["page_variant_3", "page_variant_5"]`	Optional
`timeout`	integer Minimum `0`	The number of milliseconds before the function times out and returns an error. For example, set the value to `10000` for the function to time out in 10 seconds. When you use `timeout`, use try-catch blocks to handle errors.	`10000`	Optional

The identifier object:

Attribute	Type	Description	Example	Required/optional
`id`	string	The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.	`"123456"`	Required
`provider`	string	The name of your organization's identity system, external to XM Cloud, that provided the unique guest identifier.	`"BXLP"`	Required

The geo object:

Important

In JSS Next.js apps, leave geo unset. JSS Next.js apps use geo internally to automatically capture geolocation data.

Attribute	Type	Description	Example	Required/optional
`city`	`string`	The site visitor's city address. Format: title case recommended.	`"Dublin"`	Optional
`country`	`string`	The site visitor's country address. Format: uppercase ISO 3166-1 alpha-2.	`"IE"`	Optional
`region`	`string`	The site visitor's region address. Depends on the regional structure of the country. Format: for example, for Australia, use state and territory abbreviations. For the United States, use ANSI standard INCITS 38:2009.	`"Leinster"` `"Tas"` `"CA"`	Optional

Attribute

Type

Description

Example

Required/optional

city

string

The site visitor's city address.

Format: title case recommended.

"Dublin"

Optional

country

string

The site visitor's country address.

Format: uppercase ISO 3166-1 alpha-2.

"IE"

Optional

region

string

The site visitor's region address.

Depends on the regional structure of the country.

Format: for example, for Australia, use state and territory abbreviations. For the United States, use ANSI standard INCITS 38:2009.

"Leinster"
"Tas"
"CA"

Optional

The params.utm object:

Attribute	Type	Description	Example	Required/optional
`campaign`	string	A product promotion or strategic campaign.	`"summer_sale"`	Optional
`content`	string	The element the site visitor clicked that brought them to the website, such as a banner ad or a text link.	`"textlink"`	Optional
`medium`	string	The type of link used, for example, pay-per-click or email.	`"email"`	Optional
`source`	string	The website that sent the traffic.	`"newsletter"`	Optional
`term`	string	Search terms the site visitor searched for.	`"running shoes"`	Optional

Code examples

Example 27. Running the personalize function

JSS Next.js

Here's an example of how to use the personalize function:

RequestResponse

import { useEffect } from "react";
import { init, personalize } from "@sitecore-cloudsdk/personalize/browser";
// ...

const SitecorePage = ({
  notFound,
  componentProps,
  layoutData,
  headLinks,
}: SitecorePageProps): JSX.Element => {
  // ...

  // Initialize the module using init()...

  // Run personalization:
  const personalizeRes = await personalize({
    channel: "WEB",
    currency: "EUR",
    friendlyId: "running_shoes_popup_02",
  });

  console.log("Personalized content:", personalizeRes);
  };

  initPersonalize();
  // ...
};

personalizeRes contains the API response that the experience or experiment was configured to return.

Example 29. Personalization data object with browser ID

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

RequestResponse

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

Example 30. Personalization data object with email

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

RequestResponse

const personalizationData = {
    channel: "WEB",
    currency: "EUR",
    friendlyId: "running_shoes_popup_02",
    // guest identifier:
    email: "[email protected]"
}

Example 31. Personalization data object with identifiers

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

RequestResponse

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

Example 32. Personalization data object payload with UTM parameters

If the URL of the webpage where the personalize function runs contains UTM parameters, the payload of the personalization data object will contain the UTM parameters. Consider the following URL:

RequestResponse

https://myretailsite.com?utm_source=newsletter&utm_medium=email&utm_campaign=summer_sale&utm_term=running+shoes

For this URL, the payload will contain all the UTM parameters in params.utm:

RequestResponse

{
  "channel": "WEB",
  "currency": "EUR",
  "friendlyId": "running_shoes_popup_02",
  "params": {
    "key": "value",
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "summer_sale",
      "term": "running+shoes"
    }
  }
}

Do you have some feedback for us?

If you have suggestions for improving this article,