1. @sitecore-cloudsdk/personalize

@sitecore-cloudsdk/personalize/browser

Version:

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 SitecoreAI 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 SitecoreAI 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:

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
  // ...
};

Next.js

Here's an example page.tsx script showing how to initialize the module:

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

export default function Home() {
  // Initialize the module ->
  useEffect(() => {
    initPersonalize();
  }, []);

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

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

  return (<></>);
};

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

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.

 
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

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:

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 28. Running the personalize function

Next.js

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

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

export default function Home() {
  // Initialize the module using init()...

  // Run personalization:
  const runPersonalization = async () => {
    const personalizationData = {
      channel: "WEB",
      currency: "EUR",
      friendlyId: "running_shoes_popup_02",
    };

    const personalizeRes = await personalize(personalizationData);
    console.log("Ran personalization.", personalizeRes);
  };

  return (
    <div>
      <button onClick={runPersonalization}>run personalization</button>
    </div>
  );
}

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.

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.

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.

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:

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:

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


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