@sitecore-cloudsdk/personalize/server

PersonalizeData

Version:

Type	Interface
Import path	`@sitecore-cloudsdk/personalize/server`

Event and experiment data for running interactive experiences and experiments that are live in Sitecore Personalize.

Signature

export interface PersonalizeData {
  channel: string;
  currency?: string;
  email?: string;
  friendlyId: string;
  geo?: PersonalizeGeolocation;
  identifier?: PersonalizeIdentifierInput;
  language?: string;
  params?: PersonalizeInputParams;
  pageVariantIds?: string[];
}

Properties

Name	Type	Description	Value
`channel`	`string`	Required. 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"`. Format: uppercase.	Must be one of: `"AIRPORT_KIOSK"` `"BRANCH"` `"CALL_CENTER"` `"EMAIL"` `"GDS"` `"KIOSK"` `"MOBILE_APP"` `"MOBILE_WEB"` `"SMS"` `"OFFLINE"` `"OTA"` `"OTHER"` `"WEB"`
`currency`	`string`	Optional. The alphabetic currency code of the currency the site visitor uses in your app. For example, if the site visitor selects Australian dollars as the currency, the currency is `"AUD"`. Format: uppercase ISO 4217.	`"EUR"` `"GBP"` `"USD"`
`email`	`string`	Optional. The site visitor's email address. Format: lowercase recommended.	`"[email protected]"`
`friendlyId`	`string`	Required. The unique identifier of the live interactive experience or experiment to run. To find the friendly ID in Sitecore Personalize, click the live experience or experiment to run, then click Build summary. The friendly ID is in the Details pane.	`"running_shoes_popup_02"`
`geo`	`PersonalizeGeolocation`	Optional. The site visitor's geolocation data.	`geo: { city: "Dublin", country: "IE", region: "Leinster" }`
`identifier`	`PersonalizeIdentifierInput`	Optional. The identifiers used for identifying site visitors. If set, the experience or experiment runs only for the identified site visitor.	`identifier: [{ id: "123456", provider: "BXLP" }]`
`language`	`string`	Optional. The language the site visitor interacts with your brand in. For example, if the site visitor selects the Japanese language in your app, the language is `"JA"`. Format: uppercase ISO 639. Default for browser-side events: inferred from the HTML `lang` attribute. If `lang` is not specified, the default is an empty string. Default for server-side events: empty string.	`"DE"` `"EN"` `"FR"`
`params`	`PersonalizeInputParams`	Optional. 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`. To override the automatically captured UTM parameters, specify values manually in `params.utm`.	`params: { customKey: "customValue" }`
`pageVariantIds`	`string[]`	Optional. 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"]`

`PersonalizeGeolocation` properties

Name	Type	Description	Value
`city`	`string`	Optional. The site visitor's city address. Format: title case recommended.	`"Dublin"`
`country`	`string`	Optional. The site visitor's country address. Format: uppercase ISO 3166-1 alpha-2.	`"IE"`
`region`	`string`	Optional. 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"`

Name

Type

Description

Value

city

string

Optional.

The site visitor's city address.

Format: title case recommended.

"Dublin"

country

string

Optional.

The site visitor's country address.

Format: uppercase ISO 3166-1 alpha-2.

"IE"

region

string

Optional.

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"

`PersonalizeIdentifierInput` properties

Name	Type	Description	Value
`id`	`string`	Required. The unique guest (site visitor) identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.	`"123456"`
`provider`	`string`	Required. The name of your organization's identity system, external to SitecoreAI, that provided the unique guest (site visitor) identifier.	`"BXLP"`

Name

Type

Description

Value

id

string

Required.

The unique guest (site visitor) identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.

"123456"

provider

string

Required.

The name of your organization's identity system, external to SitecoreAI, that provided the unique guest (site visitor) identifier.

"BXLP"

`params.utm` properties

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

Examples

Example 63. Personalize data object with browser ID

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

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

Example 64. Personalize data object with email

Here's an example of a personalize data object that uses the email attribute as the guest (site visitor) identifier.

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

Example 65. Personalize data object with identifiers

Here's an example of a personalize data object that uses the identifier attribute as the guest (site visitor) identifier.

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

Example 66. Personalize data object payload with UTM parameters

If the URL of the webpage where the personalize function runs contains UTM parameters, the payload of the personalize 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",
  "friendlyId": "running_shoes_popup_02",
  "params": {
    "customKey": "customValue",
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "summer_sale",
      "term": "running+shoes"
    }
  }
}

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

PersonalizeData

Signature

Properties

PersonalizeGeolocation properties

PersonalizeIdentifierInput properties

params.utm properties

Examples

`PersonalizeGeolocation` properties

`PersonalizeIdentifierInput` properties

`params.utm` properties