Marketing Cloud Personalization Web Integration

The Salesforce Interactions SDK is an extensible data capture and collection framework that you can use to track website visitors’ profile data and different user interactions on your website and send that information to Salesforce. The SDK consists of a base SDK and product-specific modules for Marketing Cloud Personalization and Salesforce CDP.

The SDK leverages a unified event data model shared across the Personalization and CDP-specific SDK modules. This unified data model allows for capturing and integrating key business objects and user and behavioral data through event capture in a consistent format across Personalization and CDP. The unified data model also enables you to use a single SDK to integrate with either Personalization, CDP, or both together.

The following table describes the SDK modules to use depending on your use of Personalization and CDP.

Products UsedUseSDK Namespace
New customers using Personalization onlyPersonalization module of the Salesforce Interactions SDKSalesforceInteractions
Existing customers that have completed their Personalization implementation or have an implementation in progressPersonalization module of the Salesforce Interactions SDKEvergage
Personalization and CDPPersonalization module of the Salesforce Interactions SDKSalesforceInteractions
CDP onlySalesforce CDP module of the Salesforce Interactions SDKSalesforceInteractions
  • If you’re an existing customer who has completed their Personalization implementation or have an implementation in progress, you can continue to leverage the Evergage namespace in your Sitemap and Web and Server-side Campaign Template code.
  • To view code samples applicable to the Evergage namespace, ensure that you select the Evergage tab in code blocks across this documentation site. Selecting the Evergage tab on a code block automatically switches all other code blocks across this site to display sample code relevant to the Evergage namespace.

The Personalization module of the Salesforce Interactions SDK facilitates the integration of your website with Personalization. This module provides functions, properties, and methods to track user behavior on your website and send that behavioral data to Personalization, enabling you to build user or visitor behavior profiles. The JavaScript beacon included with the module handles event responses containing personalization web Campaigns. Users develop these Campaigns through the Personalization UI for display on the website to qualified visitors and leverage Campaign Templates to load data, run machine learning, perform A/B testing, and run client-side display logic.

To know more about the web integration process and considerations for development planning, see Plan a Web Integration.

Key Features

The Personalization module of the Salesforce Interactions SDK provides the following features.

  • Identity and cookie management for anonymous and named identity tracking
  • Salesforce Interactions SDK JavaScript beacon for website integration
  • The Personalization Sitemap for data collection and consent management
  • Gears extensions to augment Personalization platform capabilities
  • Gears extensions for rendering web campaigns

The following sections introduce each of the preceding features of the Personalization module of the Salesforce Interactions SDK.

The Personalization module of the Salesforce Interactions SDK supports anonymous and named identity tracking using Personalization first-party cookies or by being passed identity information by the website. This system supports the client portion of the Personalization identity system by optionally updating client identity with an encrypted nonce for the primary identity to support merging profile identities across different devices and channels. For comprehensive information on how to specify user identities in Personalization, see User Identity Mapping.

Personalization First-Party Cookies

The Personalization module of the Salesforce Interactions SDK sets the following two cookies.

  • A cookie prefixed with _evga_ that stores Personalization Identities such as the anonymousId or any persisted ID.
  • A cookie prefixed with _sfid_ that stores any consents and their status provided to the Web SDK.

Both cookies end with a string of characters unique to the dataset to which the cookie belongs. These cookies can be cleared for consent management purposes when a user does not consent to cookie tracking. The cookies will default to having the secure attribute set, but can be overridden at the dataset level under Settings > General Setup > Internal Options > Web SDK Cookie Secure Attribute.

The JavaScript beacon provided with the Personalization module of the Salesforce Interactions SDK is required for managing the flow of data between the Personalization platform and the SDK libraries used in the client integration. The beacon is a lightweight JavaScript file that enables script-loading functionality on page load, acts as an event message bus, and provides the ability to bootstrap plug-ins for advanced logic and integration. Website pages that do not contain the JavaScript beacon cannot leverage Personalization's behavioral tracking or personalization capabilities. For instructions on confirming whether the JavaScript beacon is present on a website page, see Validate JavaScript Beacon Deployment.

The Personalization Sitemap system is a configuration-driven integration layer that executes within and is deployed by the Salesforce Interactions SDK. A Sitemap is developed using APIs provided by the Web SDK. A Sitemap integrates key business objects of a website into the Personalization system through event capture. Key business objects are completely customizable and include, but are not limited to, page type information and catalog items, which both support a deep understanding of user affinities within Personalization. Examples of catalog items include products, article content, categories, and other catalog objects. For more information about the Personalization Sitemap and Data Model, see the Sitemap and Data Model documentation.

The Salesforce Interactions SDK includes functions for resolving and storing consent. The Personalization module of the Salesforce Interactions SDK tracks a user if supplied with either no consent value or any value other than an OptOut consent with the purpose of Personalization. When the Personalization module sees an OptOut consent with the purpose of Personalization, it does not send events to the user until their consent status changes. The OptOut consent with the purpose of Personalization is the only consent that causes a behavior change in the Personalization module. While the module can receive and store other consents, they do not affect collecting or tracking data.

The SDK stores the most recent consent for a purpose in the _sfid cookie along with the lastUpdatedTime and lastSentTime for the consent.

Providing user consent to the SDK can happen either during initialization or by using the updateConsents method.

consent defines a consent object that accepts the following fields.

The ConsentWithMetadata object has the following shape.

You can use the following methods to update the consent object.

  • getConsents: ConsentWithMetadata[]

    Returns consent data with the last updated and sent times.

  • updateConsents = (consents: Consent | Consent[]): void

    Accepts an array of consent objects or a single consent object. This method updates the consent used by the Personalization module of the Web SDK allowing updating consent after initialization.

The Personalization module of the Salesforce Interactions SDK provides the following helpers for setting consent purpose and consent status.

ConsentPurpose

  • SalesforceInteractions namespace

  • Evergage namespace

ConsentStatus

  • SalesforceInteractions namespace

  • Evergage namespace

Not all your website's visitors and/or users consent to cookie tracking. To support consent management, the Personalization module of the Salesforce Interactions SDK has been designed to not track activity if a Consent with the Status of OptOut and the Purpose of Personalization has been provided.

During initialization, the Personalization module of the Salesforce Interactions SDK can accept a consents field in the configuration. The consents field can accept either an array of Consents or a Promise that resolves an array of Consents. When the consents field is provided during initialization, any resolved consents are used by the Personalization module of the Salesforce Interactions SDK.

The following is an example of providing user consent on initialization.

  • SalesforceInteractions namespace

  • Evergage namespace

The Personalization module of the Salesforce Interactions SDK also provides functionality to update consents through the updateConsents method. The updateConsents method can be called at any time with updated consent for the user.

When the updateConsents method is called, if a Consent is sent with the status of OptOut, the Personalization module of the Salesforce Interactions SDK sends an event to Personalization with the updated consents. If a Consent with the Purpose of Personalization is updated to OptOut, the Personalization module of the Salesforce Interactions SDK stops sending events.

The following is an example of calling the updateConsents method.

  • SalesforceInteractions namespace

  • Evergage namespace

Since the Personalization module of the Salesforce Interactions SDK does not track users that have provided an OptOut Personalization consent, we recommend providing an OptOut Personalization consent by default until a user has Opted in. The following is an example of providing an OptOut Personalization consent on initialization.

  • SalesforceInteractions namespace

  • Evergage namespace

When an OptOut Personalization consent is provided for a user, no events are tracked. In the preceding example, an OptOut Personalization Consent is provided with initialization on every page. If you wish to have the Sitemap execute for a user, you must resolve and set the user's actual consent before initializing the Sitemap.

Removing Personalization Cookies

The Personalization module of the Salesforce Interactions SDK provides the following helper function to remove Personalization cookies. You can use this helper function to remove Personalization cookies in scenarios where a user no longer consents to or explicitly requests to cease cookie tracking, or when you wish to remove cookies after a user logs out of your website.

  • SalesforceInteractions namespace

  • Evergage namespace

By default, if the domain is not specified, this helper function tries to remove cookies based on the domain configured in the SalesforceInteractions.init() function in the SalesforceInteractions SDK namespace and the Evergage.init() function in the Evergage SDK namespace that initializes the JavaScript Beacon. To remove cookies before the beacon is initialized, ensure that you specify the domain in the helper function or as part of the detail on the SalesforceInteractions.CustomEvents.OnClearCookie CustomEvent.

The JavaScript beacon provided with the Salesforce Interactions SDK supports the delivery of custom functionality to augment the client-side functionality of the Personalization platform through Gears extensions. These extensions are JavaScript files delivered and installed through various Gears developed by the Personalization development team.

You can also use Gears extensions in configured web templates to deliver campaign and personalization content directly to website code so that the website can render it. Personalization includes a built-in Handlebars Gear that supports rendering dynamic content into HTML and CSS styles using the Handlebars template language.