Sitemap Implementation

The Marketing Cloud Personalization Sitemap system is a configuration-driven integration layer that executes within and is deployed by the Personalization module of the Salesforce Interactions SDK. A Sitemap is developed using the SDK to integrate with a specific site and map key business objects into the Personalization system through event capture. A Sitemap includes page type information, which can additionally include catalog items such as products, articles, content, and categories that support the ability to gauge user interest against the catalog.

For more information on the Personalization Sitemap, see Sitemap Overview. For more information on the Personalization data model, see Data Model.

Note

In This Article

This article details the following topics related to the implementation of a Personalization Sitemap.

Sitemap Configuration Type Definitions
Sitemap API
- Resolvers
- Utility Functions
Single Page App Handling
Sitemap Localization Implementation

Example Sitemaps

The following is a list of example Sitemaps we’ve created for different types of business websites that depict how you could approach designing a Sitemap for your Personalization implementation. While the JavaScript and HTML code in these example Sitemaps are only for reference purposes, they can give you a head start in developing the Sitemap for your implementation.

Sitemap Configuration Type Definitions

A SiteMapConfig consists of the following three, separate configurations.

global: The global configuration contains objects to be monitored by Personalization on all page type configuration objects, and the default page configuration (if defined) of your site.
pageTypes: The pageTypes configuration contains objects used to detect/match each different page type to be monitored on your site.
pageTypeDefault: If defined, the objects configured in pageTypeDefault are matched when all PageConfig objects in the pageTypes array resolve to false. Do remember that the pageTypeDefault matches this way only when the sitemap contains at least one validly constructed PageConfig object. When using the SalesforceInteractions namespace, an interaction must be provided for pageTypeDefault.

The following sections describe how the preceding Sitemap configuration types are processed and provide additional information about each configuration type.

SiteMapConfig Type Processing

When the configuration for either a PageConfig object inside the pageTypes array or the pageTypeDefault matches a page on the site, the matched configuration merges with anything defined within GlobalConfig. Individual attributes are merged in the following manner.

locale : the matched PageConfig or DefaultPageConfig takes precedence
contentZones: concatenate
listeners: concatenate
onActionEvent: the function for the matched PageConfig or DefaultPageConfig executes first, followed by the function for the GlobalConfig

The result of this merge is then evaluated as expected.

1{
2  global: GlobalConfig,
3  pageTypeDefault: DefaultPageConfig,
4  pageTypes: PageConfig[]
5}

Global Config

GlobalConfig defines the additional data to be tracked if a PageConfig or DefaultPageConfig matches a specific page.

1{
2  locale?: string | () => string,
3  contentZones?: ContentZone[],
4  listeners?: Listener[],
5  onActionEvent?: (event: ActionEvent) => ActionEvent
6}

Page Types

Page type configurations use a pageTypes array to declare how to detect that a given URL or loaded page is one of the known page types. Each page type configuration must contain properties for name, action, and isMatch, which declares the function used to detect that page type. Additionally, individual page type configurations can declare Content Zones representing key parts of a page designed for personalization adjustments. The configurations can also declare other event listeners for a given page type, such as an “add to cart” listener. Page types can map to more than a single page; for example, while the Home page is an example of a page type with only a single instance of a page, the product display page (PDP) type would have separate URLs for every product on the site, but only a single page type.

For more information on page types, refer to the Page Types documentation.

PageConfig

PageConfig defines the data to be tracked for a specific page. The PageConfig object accepts the following fields.

1{
2  name: string, // required
3  isMatch: () => boolean | () => Promise<boolean>, // required
4  locale?: string | () => string,
5  interaction?: Interaction,
6  contentZones?: ContentZone[],
7  listeners?: Listener[],
8  onActionEvent?: (event: ActionEvent) => ActionEvent
9}

1{
2    name: string, // required
3    isMatch: () => boolean | () => Promise<boolean>, // required
4    locale?: string | () => string,
5    action?: string,
6    itemAction?: string,
7    catalog?: CatalogConfig,
8    cart?: CartConfig,
9    order?: OrderConfig,
10    contentZones?: ContentZone[],
11    listeners?: Listener[],
12    onActionEvent?: (event: ActionEvent) => ActionEvent
13}

The following table describes the fields that a PageConfig accepts.

Field	Expected Value Type	Required?	Description	Namespace
`name`	String	Yes	The page type that gets sent in the event when this configuration is evaluated. Example: Homepage, Product Detail	Both
`isMatch`	`() => boolean \| Promise<boolean>`	Yes	The function provided here is evaluated when the sitemap is deciding which `PageConfig` to evaluate. The sitemap only evaluates the first `PageConfig` whose `isMatch` resolves to `true`. If no `isMatch` resolves to `true`, then the `pageTypeDefault` configuration runs.	Both
`locale`	String	No	The locale of the page (for example, `en_US`). Use `locale` only if you have catalog localization enabled.	Both
`action`	String	No	The name of the action dispatched in the event when this configuration is evaluated. Important: Capture actions only if they’re necessary for personalization and targeting. Actions must have names that can be reused across users and sessions. If you dynamically populate action names, ensure that these names stay consistent across sessions for any user performing the action. Dynamic user information in action names can cause issues and should be avoided whenever possible. For more information and best practices on using actions, see Best Practices For Using Actions.	`Evergage`
`itemAction`	String	No	The name of the itemAction dispatched in the event when this configuration is evaluated.	`Evergage`
`interaction`	`Interaction`, `CatalogObjectInteraction`, `CartInteraction`, or `OrderInteraction`	No	An object describing the interaction on the page. For more information, refer to the Interaction section of this article. For more information and best practices on using actions, see Best Practices For Using Interactions.	`SalesforceInteractions`
`catalog`	`CatalogConfig`	No	The catalog data to be captured. For more information, refer to the CatalogConfig section of this article.	`Evergage`
`cart`	`CartConfig`	No	The cart data to be captured. For more information, refer to the CartConfig section of this article.	`Evergage`
`order`	`OrderConfig`	No	The order data to be captured. For more information, refer to the OrderConfig section of this article.	`Evergage`
`contentZones`	`ContentZone[]`	No	The content zones defined in the sitemap determine where Personalization campaigns are rendered throughout a website. Personalization templates reference these content zones for targeting within campaigns. For more information on content zones, refer to the Content Zones documentation.	Both
`listeners`	`Listener[]`	No	The event listeners to be bound when this configuration is evaluated. For more information, refer to the Listeners section of this article.	Both
`onActionEvent`	`(event: ActionEvent) => ActionEvent`	No	The `onActionEvent` function modifies the outgoing `ActionEvent`. This function runs whenever the sitemap builds an `ActionEvent` before sending it to Personalization. The sitemap builds the `ActionEvent` as a result of calling the `sendEvent` function or building a `PageConfig` array. If the GlobalConfig and a matched PageConfig array contain the `onActionEvent` function, then both functions are executed. The function in `PageConfig` is executed before executing the function in the `GlobalConfig` array.	Both

Default Page Config

DefaultPageConfig defines the default page configuration to use if no other page types are matched. When using DefaultPageConfig with the SalesforceInteractions namespace, an interaction must be provided.

1{
2  name: string,
3  interaction: Interaction
4}

1{
2  name: string;
3}

CatalogConfig

CatalogConfig defines the catalog data to be captured and accepts the following fields. A catalog object accepts the following fields.

Only available in the SalesforceInteractions namespace.

Important

1catalog: {
2    <ItemType>: {
3        _id: string | () => string | () => Promise<string | () => string> // required
4        categories?: string[] | () => string[] | () => Promise<string[] | () => string[]>
5        <attributes>?: value | () => value,
6        relatedCatalogObjects?: { // In case you're using 'dimensions' instead of 'relatedCatalogObjects', you can continue to do so as they both function the same way.
7            <relatedCatalogObject>?: string[] | () => string[] | () => Promise<string[] | () => string[]>
8        },
9        attributes?: {
10            <attribute>?: value | () => value
11        }
12    }
13}

The ItemType in a CatalogConfig is defined in the Catalog and Profile Objects section of the Personalization UI. An ItemType can refer to items such as products, content, blogs, or any other catalog object, whether built in or user-defined. The following table describes the fields that an ItemType array accepts.

Field	Expected Value Type	Required?	Description
`_id`	`string \| () => string \| () => Promise<string \| () => string>`	Yes	The ID of the catalog item. This field is required for an item to be tracked. Important: When capturing catalog items IDs, avoid capturing line break characters (`\n`). This character isn’t supported in IDs of catalog items, interactions, and actions. Including line breaks in the IDs can cause issues in the UI.
`categories`	`string[] \| () => string[] \| () => Promise<string[] \| () => string[]>`	No	The categories the catalog item belongs to.
`<attributes>`	`value \| () => value`	No	Use this field to define standard, built-in item attributes. Examples of attributes include `_id`, `name`, `price`, and so on.
`relatedCatalogObject`	`string[] \| () => string[] \| () => Promise<string[] \| () => string[]>`	No	Catalog objects can be assigned to other catalog objects to describe them in more detail. When so assigned, it is considered a related catalog object.
`attributes`	`value \| () => value`	No	Custom attributes on an item, as defined in the Catalog Setup section of the Personalization UI.

For more details on catalog items and item attributes, see Create a Custom Catalog Object.

CartConfig

CartConfig defines the cart data to be captured. The cart object accepts the following fields.

Only available in the SalesforceInteractions namespace.

Important

1cart: {
2    complete: {
3        <ItemType>: LineItem[]
4    }
5}

When including a CartConfig in a pageType, ensure that it follows the following structure.

Only available in the SalesforceInteractions namespace.

Important

1cart: {
2    complete: {
3        <ItemType>: {
4            lineItem: {
5                _id: string[],
6                price: double[],
7                quantity: integer[]
8            }
9        }
10    }
11}

Additionally, a user’s cart can be emptied by sending an event with an empty array of LineItems.

1{
2  cart: {
3    complete: {
4      Product: [];
5    }
6  }
7}

OrderConfig

OrderConfig defines the order data to be captured. An order object accepts the following fields.

Only available in the Evergage namespace.

Important

1order: {
2    <ItemType>: {
3        orderId: string | () => string | Promise<string | () => string>,
4        totalValue?: double | () => double | Promise<double | () => double>,
5        currency?: string | () => string | Promise<string | () => string>,
6        lineItems: LineItem[]
7    }
8}

LineItem

LineItem represents a single item in a cart/transaction. A LineItem object accepts the following fields.

Only available in the Evergage namespace.

Important

1{
2    _id: string | () => string | Promise<string | () => string>
3    price: double | () => double | Promise<value | ()=> double>
4    quantity: integer | () => integer | Promise<value | ()=> integer>
5}

Interaction

Interaction represents the interaction the user is taking on the page. An Interaction object accepts the following fields.

Only available in the SalesforceInteractions namespace.

Important

1{
2  name: string; // required
3}

CatalogObjectInteraction

CatalogObjectInteraction is an extension of Interaction that accepts a catalogObject. A CatalogObjectInteraction object accepts the following fields.

Only available in the SalesforceInteractions namespace.

Important

1{
2    name: CatalogObjectInteractionName,
3    catalogObject: {
4        type: string,
5        id: string,
6        attributes?: { [key: string]: any },
7        relatedCatalogObjects?: { [catalogObjectType: string]: string[] }
8    }
9}

For all CatalogObjectInteractions, refer to the CatalogObjectInteraction documentation.

CartInteraction

CartInteraction is an extension of Interaction that accepts information about a cart. A CartInteraction object accepts the following fields.

Only available in the SalesforceInteractions namespace.

Important

1{
2    name: CartInteractionName,
3    lineItem?: LineItem,
4    lineItems?: LineItem[]
5}

In a CartInteraction, LineItem accepts the following fields.

1{
2    catalogObjectType: string,
3    catalogObjectId: string,
4    quantity: number,
5    price?: number,
6    currency?: string,
7    attributes?: { [key: string]: any }
8}

For all CartInteractions, refer to the CartInteraction documentation.

OrderInteraction

OrderInteraction is an extension of Interaction that accepts information about an order. An OrderInteraction object accepts the following fields.

Only available in the SalesforceInteractions namespace.

Important

1{
2    name: OrderInteractionName,
3    order: {
4        id: string;
5        lineItems?: LineItem[];
6        totalValue?: number;
7        currency?: string;
8        attributes?: { [key: string]: any };
9    }
10}

In an OrderInteraction, LineItem accepts the following fields.

1{
2    catalogObjectType: string,
3    catalogObjectId: string,
4    quantity: number,
5    price?: number,
6    currency?: string,
7    attributes?: { [key: string]: any }
8}

For all OrderInteractions, refer to the OrderInteraction documentation.

CatalogConfig Utility Functions

The Personalization module of the Salesforce Interactions SDK includes the following utility function that is especially helpful for building LineItems.

1SalesforceInteractions.mcis.buildLineItemFromPageState(quantitySelector) => LineItem

1Evergage.util.buildLineItemFromPageState(quantitySelector) => LineItem

The preceding utility function returns a LineItem constructed from the data already captured on the page using the given quantitySelector to determine the number of items in the line item.

Default Page Config

The DefaultPageConfig defines what data is tracked only if all other PageConfigs resolve to false.

The DefaultPageConfig accepts the following fields.

1{
2    name: string, // required
3    locale?: string | () => string,
4    contentZones?: ContentZone[],
5    listeners?: Listener[],
6    onActionEvent?: (event: ActionEvent) => ActionEvent
7}

The DefaultPageConfig works only when the sitemap contains at least one validly constructed PageConfig object.

Note

Sitemap API

The Sitemap API is scoped on the window under Evergage.

initSitemap

Initialize the sitemap process using the provided configuration. Events are not sent to Personalization unless this function is called.

1SalesforceInteractions.initSitemap(siteMapConfig: *SiteMapConfig*) => void

1Evergage.initSitemap(siteMapConfig: *SiteMapConfig*) => void

cashDom

A small library for modern browsers that provides jQuery-style syntax to wrap modern Vanilla JS features and select elements from the DOM. For more information on Cash, refer to the Cash documentation.

1SalesforceInteractions.cashDom(selector: *String*, context) => Cash

1Evergage.cashDom(selector: *String*, context) => Cash

sendEvent

Send a custom event to Personalization.

1SalesforceInteractions.sendEvent(event: *ActionEvent*)

1Evergage.sendEvent(event: *ActionEvent*)

getSitemapResult

Get the current page state, including values in the configuration that have already been resolved.

1SalesforceInteractions.mcis.getSitemapResult();

1Evergage.getSitemapResult()

Listeners

Create a listener.

1SalesforceInteractions.listener(bind: keyof WindowEventMap, selector: string, callback: Function): Listener;

1Evergage.listener(bind: keyof WindowEventMap, selector: string, callback: Function): Listener;

You can use a listener to “listen” for user actions on a page, capture information from that action, and initiate a function or action based on the captured information. Listeners are structurally similar to jQuery’s event listeners.

The following are examples of simple listeners that bind a click to the banner of a website and dispatch an event to Personalization.

1SalesforceInteractions.listener("click", ".header-banner", () => {
2  SalesforceInteractions.sendEvent({ interaction: { name: "Banner Click" } });
3});

1Evergage.listener("click", ".header-banner", () => {
2  Evergage.sendEvent({ action: "Banner Click" });
3});

The following are namespace-specific examples of listeners that capture email addresses using a custom callback function.

1SalesforceInteractions.listener("submit", "form#subscribe", (e) => {
2  const userEmail = SalesforceInteractions.cashDom(e.target).find("#email").val();
3  if (typeof userEmail === "string" && /^.+@.+\..+$/.test(userEmail)) {
4    SalesforceInteractions.sendEvent({
5      interaction: {
6        name: "Email Capture",
7      },
8      user: {
9        identities: { emailAddress: userEmail },
10      },
11    });
12  }
13});

1Evergage.listener("submit", "form#subscribe", (e) => {
2  const userEmail = Evergage.cashDom(e.target).find("#email").val();
3  if (typeof userEmail === "string" && /^.+@.+\..+$/.test(userEmail)) {
4    Evergage.sendEvent({
5      action: "Email Capture",
6      user: {
7        attributes: { emailAddress: userEmail },
8      },
9    });
10  }
11});

Resolvers

Resolvers return functions so that they can be invoked after a page has been matched. When used in a PageConfig, the returned functions do not need to be invoked to get the final value - the underlying sitemap code handles that logic.

1SalesforceInteractions.resolvers.<resolver>

1Evergage.resolvers.<resolver>

transform functions are callbacks designed to evaluate or modify the resolved value.

1fromSelector(selector: string, transform?: (string) => string) => () => string

1SalesforceInteractions.cashDom(selector).text();

1Evergage.cashDom(selector).text();

Returns the text of the first instance of the selector in the DOM.

1fromSelectorMultiple(selector: string, transform?: (string[]) => string[]) => () => string[]

1[SalesforceInteractions.cashDom(selector).eq(0).text(), SalesforceInteractions.cashDom(selector).eq(1).text(), ...]

1[Evergage.cashDom(selector).eq(0).text(), Evergage.cashDom(selector).eq(1).text(), ...]

Returns the text of all instances of the selector in the DOM in an array.

1fromSelectorAttribute(selector: string, attribute: string, transform?: (string) => string) => () => string

1SalesforceInteractions.cashDom(selector).attr(attribute);

1Evergage.cashDom(selector).attr(attribute);

Returns the attribute of the first instance of the selector in the DOM.

1fromSelectorAttributeMultiple(selector: string, attribute: string, transform?: (string[]) => string[]) => () => string[]

1[SalesforceInteractions.cashDom(selector).eq(0).attr(attribute), SalesforceInteractions.cashDom(selector).eq(1).attr(attribute), ...]

1[Evergage.cashDom(selector).eq(0).attr(attribute), Evergage.cashDom(selector).eq(1).attr(attribute), ...]

Returns the attributes of all instances of the selector in the DOM as an array.

1fromMeta(metaName: string, transform?: (string) => string) => () => string

1SalesforceInteractions.cashDom("meta[name='" + metaName + "']")
2  .first()
3  .attr("content");

1Evergage.cashDom("meta[name='" + metaName + "']")
2  .first()
3  .attr("content");

Returns the content of the first meta tag with the given meta tag name.

1fromItemProp(itemProp: string, transform?: (string) => string) => () => string

1SalesforceInteractions.cashDom("[itemprop='" + itemProp + "']")
2  .first()
3  .attr("content");

1Evergage.cashDom("[itemprop='" + itemProp + "']")
2  .first()
3  .attr("content");

Returns the content of the first itemProp with the given itemProp.

1fromWindow(windowVar: string, transform?: (string) => string) => () => string

Returns the value from a nested object. Returns null if the nested object, or some object in the path, does not exist.

1fromJsonLd(path: string, transform?: any) => () => any

1SalesforceInteractions.cashDom("script[type='application/ld+json']").first().text();

1Evergage.cashDom("script[type='application/ld+json']").first().text();

If the path is null, the first JSON-LD script is returned after being parsed into a JavaScript object. If a path is provided, then the value of the path from the parsed JavaScript object is returned.

1buildCategoryId(selector: string, startFrom?: integer, ignoreLast?: boolean, transform?: (string) => string) => () => string

1SalesforceInteractions.cashDom(selector).eq(startFrom).text()|SalesforceInteractions.cashDom(selector).eq(startFrom+1).text()|...

1Evergage.cashDom(selector).eq(startFrom).text()|Evergage.cashDom(selector).eq(startFrom+1).text()|...

Returns a pipe-delimited string using the text of all instances of the selector.

1buildCategoryIdAttribute(selector: string, attribute: string, startFrom?: integer, ignoreLast?: boolean, transform?: (string) =>  string) => () => string

1SalesforceInteractions.cashDom(selector).eq(startFrom).attr(attribute)|SalesforceInteractions.cashDom(selector).eq(startFrom+1).attr(attribute)|...

1Evergage.cashDom(selector).eq(startFrom).attr(attribute)|Evergage.cashDom(selector).eq(startFrom+1).attr(attribute)|...

Returns a pipe-delimited string using the given attribute of all instances of the selector.

1fromCanonical(transform?: (string) => string) => () => string

Returns a canonical URL, if one exists on the page.

1fromHref(transform?: (string) => string) => () => string

Returns the value stored in window.location.href

Utility Functions

The Personalization module of the Salesforce Interactions SDK provides several utility functions that you can use to help parse data.

1SalesforceInteractions.mcis.<util>

1Evergage.util.<util>

The following table describes these utility functions in detail.

Utility Function	Description	Namespace
`buildLineItemFromPageState(quantitySelector: string) => LineItem`	Returns a `LineItem` constructed from the data already captured on the page, using the given `quantitySelector` to determine how many of the items are in the `lineItem`.	Both
`extractFirstGroup(regex: RegExp, str: string) => string`	Returns a string of the first group extracted from the provided regex.	Both
`getFloatValue(text: string) => number`	Returns a floating point number parsed from the provided string.	`Evergage`
`getIntegerValue(text: string) => number`	Returns an integer number parsed from the provided string.	`Evergage`
`getLastPathComponent(url: string) => string`	Returns the last path component for the provided URL. For example, `SalesforceInteractions.util.getLastPathComponent("https://example.example/myExamplePath.html")` returns `myExamplePath.html`.	`Evergage`
`getLastPathComponentWithoutExtension(url: string) => string`	Returns the last path component without an extension for the provided URL. For example, `SalesforceInteractions.util.getLastPathComponent("https://example.example/myExamplePath.html")` returns `myExamplePath`.	Both
`getParameterByName(name: string, url?: string) => string`	Returns the value of the provided parameter name from the provided URL. If no URL is provided, the current `location.search` of the page is used.	Both
`getPathname(url: string) => string`	Returns the `Pathname` of the provided URL.	`Evergage`
`getUtagFirstForField(fieldName: string) => any`	Returns the first value for the provided field in a `window.utag_data` object.	`Evergage`
`getValueFromNestedObject(path: string, obj?: object) => any`	Returns the value from a nested object. If an object is not provided, `window` is used. Returns `null` if the nested object, or some object in the path, does not exist.	Both
`qualifyUrl(unqualified: string) => string`	Returns a qualified URL href from an unqualified relative URL path. If unqualified is null or unprovided, returns null.	`Evergage`
`removeQueryString(url: string) => string`	Returns a URL without query strings from the provided URL.	`Evergage`
`resolveWhenTrue.bind(trueFunc: () => any, bindId?: string, timeout?: number, checkInterval?: number) => Promise<any>`	Returns a Promise that resolves when the provided `trueFunc` evaluates to `true`.DONE If `timeout` is not provided, a 2000-ms default timeout is used. If `checkInterval` is not provided, a 100-ms default interval is used to check the trueFunc. If the timeout is reached, the check is unbound. An `unbind` function is provided under `resolveWhenTrue.getBindings()`. If a `bindId` is provided, the `unbind` function is mapped to that key, otherwise a new random key is used.	Both
`resolveWhenTrue.unbind(bindId: string) => void`	When given a `bindId` unbinds that bound `resolveWhenTrue` function.	Both
`resolveWhenTrue.getBindings() => [key: string]: unbindFunction: ()`	Returns a map of currently bound `resolveWhenTrue` functions.	Both
`resolveWhenTrue.clearBindings() => void`	Clears all currently bound `resolveWhenTrue` functions.	Both

Single Page App Handling

Depending on the SDK namespace you’re using, use either of the following code snippets to reinitialize the beacon and the Sitemap when using Personalization on a single-page application (SPA).

1SalesforceInteractions.reinit();

1Evergage.reinit();

Executing the preceding code results in the following.

Depending on the SDK namespace you’re using, dispatch a SalesforceInteractions.CustomEvents.OnInit or an Evergage.CustomEvents.OnInit event.
Reinitialize the beacon with the same settings as the initial page load (for example, cookieDomain).
Rerun the sitemap using the same configuration as the initial page load.
Send activity timing for the previous page.
Start activity timers for the current page.

Ensure that you wrap the reinitialization function in logic to determine when to reinitialize the beacon and sitemap. The following is a sample sitemap code that includes logic to reinitialize the beacon and sitemap when the URL changes without a full page load.

The following sitemap code examples are for illustrative purposes only. We recommend considering other ways of using the reinitialization function that better suits your specific use case, and the way your site functions.

Note

1SalesforceInteractions.init().then(() => {
2
3    const config = {
4        global: {},
5        pageTypes: [
6            {
7                name: "home",
8                interaction: {
9                    name: "Homepage"
10                },
11                isMatch: () => /home/.test(window.location.href);
12            }
13        ]
14    };
15
16    /*
17        Check for URL change every 2 seconds. If URL has changed, reinitialize beacon and sitemap.
18    */
19    const handleSPAPageChange = () => {
20        let url = window.location.href;
21        const urlChangeInterval = setInterval(() => {
22            if (url !== window.location.href) {
23                url = window.location.href;
24                SalesforceInteractions.reinit();
25            }
26        }, 2000);
27    }
28
29    handleSPAPageChange();
30
31    SalesforceInteractions.initSitemap(config);
32})

1Evergage.init().then(() => {
2
3    const config = {
4        global: {},
5        pageTypes: [
6            {
7                name: "home",
8                isMatch: () => /home/.test(window.location.href);
9            }
10        ]
11    };
12
13    /*
14        Check for URL change every 2 seconds. If URL has changed, reinitialize beacon and sitemap.
15    */
16    const handleSPAPageChange = () => {
17        let url = window.location.href;
18        const urlChangeInterval = setInterval(() => {
19            if (url !== window.location.href) {
20                url = window.location.href;
21                Evergage.reinit();
22            }
23        }, 2000);
24    }
25
26    handleSPAPageChange();
27
28    Evergage.initSitemap(config);
29})

Sitemap Localization Implementation

The localization setting enables a single dataset to cater to a site with multiple languages and locales while leveraging the same catalog and sitemap across those languages and locales. The use of localization requires sending the locale attribute in an event.

To use catalog localizations, you must check the Enable Localization of Catalog Metadata Based on Page Locale setting in a catalog’s settings via the Personalization UI by navigating to Settings > Catalog and Profile Objects.

Important

Locales must be set in a specific format of an ISO 639 alpha-2 language code, followed by an underscore, followed by an ISO 3166 alpha-2 country code. The following list contains examples of valid locales.

en_US
en_AU
en_CA
zh_CN
en_GB
pt_PT
en_HK
zh_HK

Example: Setting Locale in the Global Configuration

The following is an example of a View Item event that depicts how to send an event with a locale. You can set the locale on the global, pageTypeDefault, and individual pageTypes configurations in the SiteMapConfig. You can set the locale manually in events tracked through sendEvent functions.

1SalesforceInteractions.init().then(() => {
2  const buildLocale = () => {
3    let locale = SalesforceInteractions.CashDom("meta[type='locale']").attr("content");
4    return locale;
5  };
6
7  const config = {
8    global: {
9      locale: buildLocale(),
10    },
11    pageTypeDefault: {
12      name: "default",
13    },
14    pageTypes: [
15      {
16        name: "home",
17        interaction: {
18          name: "Homepage",
19        },
20        isMatch: () => {
21          return window.location.pathname === "/";
22        },
23      },
24    ],
25  };
26
27  SalesforceInteractions.initSitemap(config);
28});

1Evergage.init().then(() => {
2  const buildLocale = () => {
3    let locale = Evergage.CashDom("meta[type='locale']").attr("content");
4    return locale;
5  };
6
7  const config = {
8    global: {
9      locale: buildLocale(),
10    },
11    pageTypeDefault: {
12      name: "default",
13    },
14    pageTypes: [
15      {
16        name: "home",
17        action: "Homepage",
18        isMatch: () => {
19          return window.location.pathname === "/";
20        },
21      },
22    ],
23  };
24
25  Evergage.initSitemap(config);
26});

Catalog Configurations in Different Locales

When building catalog configurations in a sitemap, different locales can all use the same configuration. Localized attributes are all on the same item in Personalization. Therefore, when selecting which _id to use for a Catalog Item, or a Catalog Item’s related catalog objects, ensure that you select an _id that does not change depending on the page’s locale. Failing to do so creates extra Catalog Items and related catalog objects in the catalog and split attribution for users between different site locales. All item types can be localized.

For products, ensure that currency, if available, is captured in the catalog along with price. The currency attribute takes an ISO 4217 3-character string currency code as its value and can change based on locale.

The following are example catalog objects with a currency attribute specified.

1catalogObject: {
2    type: "Product",
3    id: getProductId(),
4    attributes: {
5        name: getProductName(),
6        price: getProductPrice(),
7        currency: "AUD"
8    }
9}

1catalog: {
2    Product: {
3        _id: getProductId(),
4        name: getProductName(),
5        price: getProductPrice(),
6        currency: "AUD"
7    }
8}

The following list contains examples of valid currencies.

USD
AUD
THB
EUR
BRL
DKK

Order Configuration in Different Locales

When creating an order configuration on a dataset that includes locales, an additional field in the order configuration is required to calculate total revenue correctly. The currency attribute takes an ISO 4217 3-character string currency code as its value. If no currency is provided, the default currency on the dataset is applied as the currency for items in the order object.

The following are example order objects with a currency attribute specified.

1{
2  ...
3  order: {
4    id: "testOrder123",
5    totalValue: 120.25,
6    currency: "AUD",
7    lineItems: LineItem[]
8  }
9  ...
10}

1{
2    ...
3      order: {
4          Product: {
5              orderId: "testOrder123",
6              totalValue: 120.25,
7              currency: "AUD",
8              lineItems: {
9                  _id: string[],
10                  price: double[],
11                  quantity: integer[]
12                }
13            }
14        }
15    ...
16}

Sitemap Implementation

Sitemap Configuration Type Definitions

SiteMapConfig Type Processing

Global Config

Page Types

PageConfig

Default Page Config

CatalogConfig

CartConfig

OrderConfig

LineItem

Interaction

CatalogObjectInteraction

CartInteraction

OrderInteraction

CatalogConfig Utility Functions

Default Page Config

Sitemap API

initSitemap

cashDom

sendEvent

getSitemapResult

Listeners

Resolvers

Utility Functions

Single Page App Handling

Sitemap Localization Implementation

Example: Setting Locale in the Global Configuration

Catalog Configurations in Different Locales

Order Configuration in Different Locales

See Also