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 support advanced filtering logic in your recommenders. Dynamic variables reduce the number of recommenders you need to deliver your use cases. 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. The value 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 is `blue`.

Define a Dynamic Context Variable

Define dynamic context variables in the Interactions SDK Sitemap globally in the global configuration. Alternatively, define them for specific page types in 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...

Dynamic context variables work with string, number, and date filter fields. Use dynamic context variables with single-value operators, the Between operator (minimum and maximum values), and date-specific operators such as Last/Next Number of Days and Last/Next Number of Minutes.

To learn more about advanced filtering with dynamic context variables, see Filter Recommendations Using Dynamic Context Variables.

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