Set Up Dynamic Context Variables

Use dynamic context variables to send user-defined attributes to the Personalization service with every personalization request. These attributes help refine recommendation responses and enable advanced filtering logic in your recommenders. By using dynamic variables, you can reduce the number of recommenders needed to deliver your use cases. You can define context variables in the Interactions SDK sitemap globally or for specific page types.

Context Variable Fields

A dynamic context variable contains two fields: a name and a value.

Field Name	Type	Required	Description
`name`	String	Yes	The name of the contextual attribute. For example, `color`.
`value`	String, Function, or Promise	Yes	The value of the contextual attribute. This can be a static string, a function that returns a string, or a promise that resolves to a string. For example, if the name is `color`, the value could be `blue`.

Define a Dynamic Context Variable

You can define dynamic context variables in the Interactions SDK sitemap globally using the global configuration. Alternatively, you can define them for specific page types using the pageTypes configuration.

Example: Defining dynamic context variables in the global configuration of the sitemap.

1const sitemapConfig = {
2  global: {
3    contextualAttributes: {
4      loyaltyTier: "GOLD",
5      story: SalesforceInteractions.resolvers.fromSelector("#stories"),
6    },
7  }, // ...The rest of your sitemap configuration
8};

Example: Defining dynamic context variables in the pageTypes configuration of the sitemap.

1...
2pageTypes: [
3  {
4    name: "Product",
5    isMatch: () => window.location.pathname.includes("/product/"),
6    contextualAttributes: {
7      categoryAttribute: "Footwear",
8      colorAttribute: SalesforceInteractions.cashDom('.btn.btn-primary.btn-lg').text()
9    }
10  }
11],
12...

Reserved Contextual Attributes

The Interactions SDK automatically sends a set of standard contextual attributes with every personalization request. You can override some of these attributes in your sitemap configuration, but if the SDK has a valid value for an attribute, it overwrites your custom value. Before overriding a reserved attribute, verify that your custom value takes precedence in your implementation and that it doesn’t interfere with expected personalization results.

Attribute	Description	Value override allowed?	Channel
`dataspace`	The dataspace for the personalization request.	No	Web, Mobile
`anchorId`	The identifier of the anchor item (for example, a product or content item) on the current page.	Yes	Web, Mobile
`anchorType`	The Data Model Object name associated with the anchor item.	Yes	Web, Mobile
`individualId`	Unique identifier of the website visitor, generated by the SDK. This typically corresponds to a device ID.	No	Web
`channel`	The channel from which the request originates, determined by the SDK in use. The SDK sends a fixed value of ‘Web’ or ‘Mobile’. For example, `Web`, `Mobile`, `Flow`, `Email`, `SMS`, `WhatsApp`, `POS`, `ATM`, `Service Cloud`, `Sales Cloud`, `Agent`, `Server`, `OTT`.	No	Web, Mobile
`channelContext`	The hostname for web, or the mobile app identifier for mobile. For example, `salesforce.com`.	No	Web, Mobile
`locale`	The locale used to filter and rank recommendations for multi-locale deployments. This value is not set automatically by the SDK. For example, `en_US`.	Yes	Web, Mobile
`requestUrl`	The URL from which the personalization request was made. For example, `https://commercecloud.salesforce.com/s/nto/default/home`.	No	Web
`pageType`	The page type from the sitemap where the personalization request originated. For example, `Product`.	Yes	Web
`interaction`	The interaction name from the page type where the personalization request originated.	Yes	Web
`p13n_sys_requestTimeZone`	The browser’s time zone. For example, `Europe/Vienna`.	No	Web
`utm_source`	UTM source parameter captured from the page URL.	No	Web
`utm_campaign`	UTM campaign parameter captured from the page URL.	No	Web
`utm_medium`	UTM medium parameter captured from the page URL.	No	Web
`utm_content`	UTM content parameter captured from the page URL.	No	Web
`utm_term`	UTM term parameter captured from the page URL.	No	Web

For more information on how to use these contextual attributes for advanced filtering, see Filter Recommendations Using Dynamic Context Variables.