@sitecore-cloudsdk/events/server

Version: 0.3

The server module provides the following functions to capture and send events from the server side:

Function

Description

init

Initializes the module.

pageView

Sends a VIEW event.

identity

Sends an IDENTITY event.

event

Sends a custom event.

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

Next.js

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/events/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 events/server module.");
  // <- Initialize the module

  return res;
};

pageView(req[, eventData])

This asynchronous function sends a VIEW event.

The VIEW event captures the site visitor's action of viewing a webpage in your app. It triggers every time your webpage loads. You must send VIEW events from all webpages where you want to track site visitor behavior.

We recommend that you capture VIEW events on the following webpage types:

  • Home

  • Search results

  • Product description

  • Payment

  • Confirmation

  • Promotional offers

The VIEW event also lets you capture data such as the name of the page where the VIEW event triggered, the referrer URL, UTM parameters, and whether the page view triggered on a personalized page variant created in XM Cloud Pages Personalize.

Parameters

Parameter

Type

Description

Required/optional

req

object

The HTTP request.

Required

eventData

eventData object

All the required and optional data about a VIEW event.

Optional

eventData

Use the following attributes when creating the eventData object for VIEW events:

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

extensionData

object

Any custom data you want to collect about an event in addition to the values you provided in the other attributes in eventData.

This object can contain maximum 50 custom attributes of your choice.

Use a flat object structure. Nested objects will be automatically flattened, and keys will be renamed as necessary.
RequestResponse
{ customKey: "customValue" }

Optional

includeUTMParameters

boolean

Specify whether to add every UTM parameter from the URL of the current webpage to the event object.

The default is true.

true or false

Optional

language

string (uppercase ISO 639)

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

This is a custom value of your choice.

For server-side events, the default is an empty string.

  • "DE"

  • "EN"

  • "FR"

Optional

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

For server-side events, the default is an empty string.

  • "Home Page"

  • "home"

  • "contact-us.html"

Optional

pageVariantId

string

The ID of a personalized page variant.

"page_variant_3"

Optional

referrer

string or null

The URI of the webpage that linked to the webpage where the event was captured.

For server-side events, if you don't set a value, it will be set to null.

  • "https://www.example.com/"

  • null

Optional

Code examples

Example 21. Running the pageView function

Next.js

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

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

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

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

  // Send event:
  const pageViewRes = await pageView(req);
  console.log("Sent VIEW event.", pageViewRes);

  return res;
};


Example 22. Event data object for a VIEW event

Here's an example eventData object:

RequestResponse
let eventData: any = {
  language: "EN",
  page: "home",
  pageVariantId: "page_variant_3",
  extensionData: {customKey: "customValue"},
};

By default, VIEW events include UTM parameters. Consider the following URL:

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

When you send a VIEW event from the previous URL, the event data will contain all the UTM parameters:

RequestResponse
{ 
  "language": "EN",
  "page": "home",
  "pageVariantId": "page_variant_3",
  "extensionData": "{'customKey': 'customValue'}",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "summer_sale",
  "utm_term": "running shoes"
}


identity(req, eventData)

This asynchronous function sends an IDENTITY event.

The IDENTITY event is used to resolve the identity of an anonymous site visitor of your app and turn them into a known customer. When Sitecore CDP receives an IDENTITY event, it runs a linking algorithm to try to match guest data from separate guest profiles, based on your organization's identity rules. We recommend that you learn about identity resolution in Sitecore CDP before you start sending IDENTITY events.

You can optionally include personally identifiable information (PII), such as email, first name, and last name.

Parameters

Parameter

Type

Description

Required/optional

req

object

The HTTP request.

Required

eventData

eventData object

All the required and optional data about an IDENTITY event. You can include personally identifiable information (PII) in this object.

Required

eventData

Use the following attributes when creating the eventData object for IDENTITY events:

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

extensionData

object

Any custom data you want to collect about an event in addition to the values you provided in the other attributes in eventData.

This object can contain maximum 50 custom attributes of your choice.

Use a flat object structure. Nested objects will be automatically flattened, and keys will be renamed as necessary.
RequestResponse
{ customKey: "customValue" }

Optional

identifiers

array of objects

The identifiers that are used to identify the users of your app.
RequestResponse
identifiers: [{
    "id": "123456",
    "provider": "BXLP"
}]

Required

language

string (uppercase ISO 639)

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

This is a custom value of your choice.

For server-side events, the default is an empty string.

  • "DE"

  • "EN"

  • "FR"

Optional

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

For server-side events, the default is an empty string.

  • "Home Page"

  • "home"

  • "contact-us.html"

Optional

email

string (lowercase recommended)

The email address of the guest.

"[email protected]"

Optional

title

string (title case)

The title of the guest.

  • "Miss"

  • "Mr"

  • "Mrs"

  • "Ms"

Optional

firstName

string (title case recommended)

The first name of the guest.

"Jane"

Optional

lastName

string (title case recommended)

The last name of the guest.

"Doe"

Optional

gender

string

The gender of the guest.

"female"

Optional

dob

string (ISO 8601)

The date of birth of the guest.

"1984-04-15"

Optional

mobile

string

The mobile number of the guest.

"+3531234567"

Optional

phone

string

The phone number of the guest.

"+3531234567"

Optional

street

array of strings (title case recommended)

The street address of the guest.

["Tara Street"]

Optional

city

string (title case recommended)

The city address of the guest.

"Dublin"

Optional

state

string (title case recommended)

The state address of the guest.

"Oregon"

Optional

country

string (uppercase ISO 3166-1 alpha-2)

The country address of the guest.

"IE"

Optional

postalCode

string

The postal code of the guest.

"D2"

Optional

The identifiers array of objects:

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

expiryDate

string (ISO 8601)

The date the unique guest identifier expires. This is determined by your organization's identity system.

"2024-04-15T08:39:44.868Z"

Optional

Code examples

Example 23. Running the identity function

Next.js

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

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

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

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

  // Send event:
  let eventData: any = {
    identifiers: [
        {
            id: "123456",
            provider: "BXLP"
        }
    ]
  };

  const identityRes = await identity(req, eventData);
  console.log("Sent IDENTITY event.", identityRes);

  return res;
};


Example 24. Event data object for an IDENTITY event

Here's an example eventData object:

RequestResponse
let eventData: any = {
  channel: "WEB",
  currency: "EUR",
  email: "[email protected]",
  title: "Miss",
  firstName: "Jane",
  lastName: "Doe",
  gender: "female",
  dob: "1984-04-15",
  mobile: "+3531234567",
  phone: "+3531234567",
  street: ["Tara Street"],
  city: "Dublin",
  country: "IE",
  identifiers: [
    {
      id: "123456",
      provider: "BXLP",
    },
  ],
  extensionData: { customKey: "customValue" },
};


event(req, eventData)

This asynchronous function sends a custom event with custom data of your choice.

Using a custom event, you can track any custom behavior of your choice, for example, a site visitor's action of clicking a component or adding a product item to their wish list.

Parameters

Parameter

Type

Description

Required/optional

req

object

The HTTP request.

Required

eventData

eventData object

All the required and optional data about a custom event.

Required

eventData

Use the following attributes when creating the eventData object for custom events:

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

extensionData

object

Any custom data you want to collect about an event in addition to the values you provided in the other attributes in eventData.

This object can contain maximum 50 custom attributes of your choice.

Use a flat object structure. Nested objects will be automatically flattened, and keys will be renamed as necessary.
RequestResponse
{ customKey: "customValue" }

Optional

type

string

The type of the event. You can set this to any value of your choice that is not a reserved event name.

Reserved event names:

We recommend that you set this to a unique value by including, for example, your site name in the value.

"myretailsite:CLICKED_PROMO"

Required

Code examples

Example 25. Running the event function

Next.js

Here's an example of how to use the event function to send a custom event named "myretailsite:CLICKED_PROMO":

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

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

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

  // Send event:
  let eventData: any = {
    type: "myretailsite:CLICKED_PROMO",
  };

  const eventRes = await event(req, eventData);
  console.log("Sent custom event.", eventRes);

  return res;
};


Example 26. Event data object for a custom event

Here's an example eventData object:

RequestResponse
let eventData: any = {
  channel: "WEB",
  currency: "EUR",
  type: "myretailsite:CLICKED_PROMO",
  extensionData: { customKey: "customValue" },
};


Do you have some feedback for us?

If you have suggestions for improving this article,