@sitecore-cloudsdk/events

@sitecore-cloudsdk/events
@sitecore-cloudsdk/events/server

@sitecore-cloudsdk/events/server

Version:

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

Overview

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`	object	Details about your SitecoreAI instance and cookie settings.	Required
`req`	object	The HTTP request.	Required
`res`	object	The HTTP response.	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

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

Code examples

Next.js

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

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(
    {
      sitecoreEdgeContextId: "<YOUR_CONTEXT_ID>",
      siteName: "<YOUR_SITE_NAME>",
      enableServerCookie: true,
    },
    req,
    res
  );

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

  return res;
};

pageView(eventData, req[, extensionData])

Overview

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.

JSS apps automatically capture VIEW events, with no coding required.

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
`eventData`	object	All the required and optional data about an event.	Required
`req`	object	The HTTP request.	Required
`[extensionData]`	object	Any custom data you want to collect about an event in addition to what's 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.	Optional

Parameter

Type

Description

Required/optional

eventData

object

All the required and optional data about an event.

Required

req

object

The HTTP request.

Required

[extensionData]

object

Any custom data you want to collect about an event in addition to what's 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.

Optional

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

extensionData object

All attributes are optional.

Code examples

Example 24. Running the pageView function

Next.js

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

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:
  let eventData: any = {
    channel: "WEB",
    currency: "EUR",
  };

  let extensionData: any = {
    customKey: "customValue",
  };

  const pageViewRes = await pageView(eventData, req, extensionData);
  console.log("Sent VIEW event.", pageViewRes);

  return res;
};

Example 25. Event data object for a VIEW event

Here's an example eventData object:

let eventData: any = {
  channel: "WEB",
  currency: "EUR",
  language: "EN",
  page: "home",
  pageVariantId: "page_variant_3",
};

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

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:

{ 
  "channel": "WEB",
  "currency": "EUR",
  "language": "EN",
  "page": "home",
  "pageVariantId": "page_variant_3",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "summer_sale",
  "utm_term": "running shoes"
}

Example 26. extensionData object

Here's an example extensionData object containing custom data:

let extensionData: any = {
  customKey: "customValue",
};

identity(eventData, req[, extensionData])

Overview

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
`eventData`	object	All the required and optional data about an event. You can include personally identifiable information (PII) in this object.	Required
`req`	object	The HTTP request.	Required
`[extensionData]`	object	Any custom data you want to collect about an event in addition to what's 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.	Optional

Parameter

Type

Description

Required/optional

eventData

object

All the required and optional data about an event.

You can include personally identifiable information (PII) in this object.

Required

req

object

The HTTP request.

Required

[extensionData]

object

Any custom data you want to collect about an event in addition to what's 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.

Optional

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"`.	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
`identifiers`	array of objects	The identifiers that are used to identify the users of your app.	`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.	`"1983-04-15T00:00"`	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.	`"2025-04-15T08:39:44.868Z"`	Optional

extensionData object

All attributes are optional.

Code examples

Example 27. Running the identity function

Next.js

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

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 = {
    channel: "WEB",
    currency: "EUR",
    email: "[email protected]",
    firstName: "Jane",
    lastName: "Doe",
    identifiers: [
        {
            id: "123456",
            provider: "BXLP"
        }
    ]
  };

  let extensionData: any = {
    customKey: "customValue",
  };

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

  return res;
};

Example 28. Event data object for an IDENTITY event

Here's an example eventData object:

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

Example 29. extensionData object

Here's an example extensionData object containing custom data:

let extensionData: any = {
  customKey: "customValue",
};

event(type, eventData, req[, extensionData])

Overview

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.

Tip

We recommend that you give your event a unique name by including, for example, your site name in the name. Example: myretailsite:ADD_TO_WISH_LIST.

Parameters

Parameter	Type	Description	Required/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: Any event name starting with `"SC_"` `"ADD"` - standard ADD event. `"ADD_CONSUMERS"` - standard ADD_CONSUMERS event. `"ADD_CONTACTS"` - standard ADD_CONTACTS event. `"CAMPAIGN_TRACKING"` - internally reserved event. Do not use. `"CHECKOUT"` - standard CHECKOUT event. `"CLEAR_CART"` - standard CLEAR_CART event. `"CONFIRM"` - standard CONFIRM event. `"FEEDBACK"` - FEEDBACK event. `"IDENTITY"` - standard IDENTITY event. `"INTERACTION"` - internally reserved event. Do not use. `"ORDER_CHECKOUT"` - standard ORDER_CHECKOUT event. `"PAYMENT"` - standard PAYMENT event. `"SUBSCRIPTION"` - internally reserved event. Do not use. `"SEARCH"` - standard SEARCH event. `"TRACKING"` - internally reserved event. Do not use. `"VIEW"` - standard VIEW event.	Required
`eventData`	object	All the required and optional data about an event.	Required
`req`	object	The HTTP request.	Required
`[extensionData]`	object	Any custom data you want to collect about an event in addition to what's 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.	Optional

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

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

extensionData object

All attributes are optional.

Code examples

Example 30. 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":

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 = {
    channel: "WEB",
    currency: "EUR",
  };

  let extensionData: any = {
    customKey: "customValue",
  };

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

  return res;
};

Example 31. Event data object for a custom event

Here's an example eventData object:

let eventData: any = {
  channel: "WEB",
  currency: "EUR"
};

Example 32. extensionData object

Here's an example extensionData object containing custom data:

let extensionData: any = {
  customKey: "customValue",
};

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