@sitecore-cloudsdk/personalize/server

Current version: 0.3
Note

In your JSS Next.js application, you can only use the browser-side functions of the Cloud SDK, available in the package's browser module.

This module provides the following functions to run Sitecore Personalize personalizations from the server side:

Function

Description

init

Initializes the module.

personalize

Runs interactive full stack experiences and interactive full stack experiments that are live in Sitecore Personalize.

init(req, res, 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

req

object

The HTTP request.

Required

res

object

The HTTP response.

Required

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

enableServerCookie

boolean

Whether to set cookies from the server 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

Here's an example middleware.ts script showing how to initialize the module:

RequestResponse

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { init } from "@sitecore-cloudsdk/personalize/server";

export async function middleware(req: NextRequest) {
  const res = NextResponse.next();

  // Initialize the module ->
  await init(req, res,
    {
      sitecoreEdgeContextId: "<YOUR_CONTEXT_ID>",
      siteName: "<YOUR_SITE_NAME>",
      enableServerCookie: true,
    }
  );

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

  return res;
};

personalize(req, personalizationData)

This asynchronous function runs interactive full stack 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

req

object

The HTTP request.

Required

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".

If you don't set a value, this attribute will not be part of the event data.

Must be one of:

  • "AIRPORT_KIOSK"

  • "BRANCH"

  • "CALL_CENTER"

  • "EMAIL"

  • "GDS"

  • "KIOSK"

  • "MOBILE_APP"

  • "MOBILE_WEB"

  • "SMS"

  • "OFFLINE"

  • "OTA"

  • "OTHER"

  • "WEB"

Optional

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".

If you don't set a value, this attribute will not be part of the event data.

  • "EUR"

  • "GBP"

  • "USD"

Optional

friendlyId

string

The unique identifier of a live interactive full stack experience or live interactive full stack 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

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

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

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

RequestResponse

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { init, personalize } from "@sitecore-cloudsdk/personalize/server";

export async function middleware(req: NextRequest) {
  const res = NextResponse.next();

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

  // Run personalization:
  const personalizationData = {
    friendlyId: "running_shoes_popup_02",
  };

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

  return res;
};


Example 34. 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 = {
  friendlyId: "running_shoes_popup_02",
  // optional attributes:
  params: { key: "value" }
};


Example 35. 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 = {
    friendlyId: "running_shoes_popup_02",
    // guest identifier:
    email: "[email protected]"
}


Example 36. 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 = {
    friendlyId: "running_shoes_popup_02",
    // guest identifier:
    identifier: {
        id: "123456",
        provider: "BXLP"
    }
}


Example 37. 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

{
  "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,