# Marketing Cloud Personalization Web Integration ## Salesforce Interactions SDK 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 Data Cloud (formerly Customer Data Platform). The SDK uses a unified event data model shared across the Personalization and Data Cloud 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 Data Cloud. The unified data model also enables you to use a single SDK to integrate with either Personalization, Data Cloud, or both together. The following table describes the SDK modules to use depending on your use of Personalization and Data Cloud. | Products Used | Use | SDK Namespace | | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------ | | New customers using Personalization only | Personalization module of the Salesforce Interactions SDK | `SalesforceInteractions` | | Existing customers that have completed their Personalization implementation or have an implementation in progress | Personalization module of the Salesforce Interactions SDK | `Evergage` | | Personalization and Data Cloud | Personalization module of the Salesforce Interactions SDK | `SalesforceInteractions` | | Data Cloud only | Data Cloud module of the Salesforce Interactions SDK | `SalesforceInteractions` | :::important - If you’re an existing customer who has completed their Personalization implementation or have an implementation in progress, you can continue to use the `Evergage` namespace in your Sitemap and Web and Server-side Campaign Template code. - We've provided sample code for both SDK namespaces wherever applicable. When copying sample code from articles, ensure that you copy code meant only for the SDK namespace you're using. ::: ## Personalization Module of the Salesforce Interactions SDK 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](/docs/marketing/personalization/guide/campaign-development.md). Users develop these Campaigns through the Personalization UI for display on the website to qualified visitors and use [Campaign Templates](/docs/marketing/personalization/guide/personalization-template-system.md) 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](/docs/marketing/personalization/guide/web-integration-planning.md). ### 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. ## Identity and Cookie Management 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](/docs/marketing/personalization/guide/user-identity-mapping.md) 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](/docs/marketing/personalization/guide/user-identity-mapping.md). ### 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](#consent-management-through-the-sitemap) purposes when a user doesn’t consent to cookie tracking. The cookies default to having the secure attribute set, but can be overridden at the dataset level under **Settings** > **General Setup** > **Advanced Options** > **Web SDK Cookie Secure Attribute**. ## Web SDK JavaScript Beacon 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. Webpages that don’t contain the JavaScript beacon can’t use 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](/docs/marketing/personalization/guide/validate-javascript-beacon-deployment.md). ## Sitemap 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 customizable and include, but aren’t 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](/docs/marketing/personalization/guide/personalization-sitemap.md) and [Data Model](/docs/marketing/personalization/guide/data-modeling.md) documentation. ## Consent Management 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 doesn’t 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 don’t 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. ### The Consent Object `consent` defines a consent object that accepts the following fields. ```typescript { purpose: string, // The purpose for the consent. Example: Personalization provider: string, // The consent provider. status: string // The consent status. Example: OptIn or OptOut } ``` The `ConsentWithMetadata` object has the following shape. ```typescript { consent: Consent, lastUpdateTime: Date, // The last time the consent was updated lastSentTime?: Date // The last time the consent was sent in an event } ``` ### Consent Methods 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. ### Consent Helpers The Personalization module of the Salesforce Interactions SDK provides the following helpers for setting consent purpose and consent status. #### ConsentPurpose ```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"} SalesforceInteractions.mcis.ConsentPurpose = { Personalization: "Personalization", }; ``` ```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"} Evergage.ConsentPurpose = { Personalization: "Personalization", }; ``` #### ConsentStatus ```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"} SalesforceInteractions.ConsentStatus = { OptIn: "Opt In", OptOut: "Opt Out", }; ``` ```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"} Evergage.ConsentStatus = { OptIn: "Opt In", OptOut: "Opt Out", }; ``` ### Consent Management Through the Sitemap 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 are examples of providing user consent on initialization. ```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"} SalesforceInteractions.init({ consents: new Promise((resolve) => { SalesforceInteractions.cashDom("#opt-in-personalization").on("click", () => { resolve([ { provider: "Consent Provider", purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization, status: SalesforceInteractions.ConsentStatus.OptIn, }, ]); }); SalesforceInteractions.cashDom("#opt-out-personalization").on("click", () => { resolve([ { provider: "Consent Provider", purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization, status: SalesforceInteractions.ConsentStatus.OptOut, }, ]); }); }), }); ``` ```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"} Evergage.init({ consents: new Promise((resolve) => { Evergage.cashDom("#opt-in-personalization").on("click", () => { resolve([ { provider: "Consent Provider", purpose: Evergage.ConsentPurpose.Personalization, status: Evergage.ConsentStatus.OptIn, }, ]); }); Evergage.cashDom("#opt-out-personalization").on("click", () => { resolve([ { provider: "Consent Provider", purpose: Evergage.ConsentPurpose.Personalization, status: Evergage.ConsentStatus.OptOut, }, ]); }); }), }); ``` ### Updating Consent Using the updateConsents Method 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 are examples of calling the `updateConsents` method. ```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"} const sitemapConfig = { global: { listeners: [ SalesforceInteractions.listener("click", "#opt-in-personalization", () => { const consent = { provider: "Consent Provider", purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization, status: SalesforceInteractions.ConsentStatus.OptIn }; SalesforceInteractions.updateConsents(consent); }), SalesforceInteractions.listener("click", "#opt-out-personalization", () => { const consent = { provider: "Consent Provider", purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization, status: SalesforceInteractions.COnsentStatus.OptOut }; SalesforceInteractions.updateConsents(consent); }) ] } ... } ``` ```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"} const sitemapConfig = { global: { listeners: [ Evergage.listener("click", "#opt-in-personalization", () => { const consent = { provider: "Consent Provider", purpose: Evergage.ConsentPurpose.Personalization, status: Evergage.ConsentStatus.OptIn }; Evergage.updateConsents(consent); }), Evergage.listener("click", "#opt-out-personalization", () => { const consent = { provider: "Consent Provider", purpose: Evergage.ConsentPurpose.Personalization, status: Evergage.ConsentStatus.OptOut }; Evergage.updateConsents(consent); }) ] } ... } ``` ### Providing Default OptOut Personalization Consent Since the Personalization module of the Salesforce Interactions SDK doesn’t 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 are examples of providing an `OptOut` Personalization consent on initialization. ```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"} SalesforceInteractions.init({ consents: [ { provider: "Consent Provider", purpose: SalesforceInteractions.mcis.ConsentPurpose.Personalization, status: SalesforceInteractions.ConsentStatus.OptOut, }, ], }).then(() => { // Logic to get the visitors actual consent // Sitemap }); ``` ```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"} Evergage.init({ consents: [ { provider: "Consent Provider", purpose: Evergage.ConsentPurpose.Personalization, status: Evergage.ConsentStatus.OptOut, }, ], }).then(() => { // Logic to get the visitors actual consent // Sitemap }); ``` 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 functions 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. ```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"} document.dispatchEvent(new CustomEvent(SalesforceInteractions.CustomEvents.OnClearCookie), { detail: { options: { domain: domain, }, }, }); ``` ```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"} Evergage.removeCookies(domain); ``` By default, if the `domain` isn’t 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. ## Web SDK Gears Extensions 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 Gear extensions. These extensions are JavaScript files delivered and installed through various Gears developed by the Personalization development team. :::important Gear development is managed by Personalization. You can file Gear development requests as feature requests on the [Salesforce IdeaExchange](https://trailblazer.salesforce.com/ideaSearch?filter=Marketing+%3E+Interaction+Studio) portal for review by the Personalization Product team members. ::: ## Web Campaign Templates You can also use Gears extensions in configured [web templates](/docs/marketing/personalization/guide/personalization-template-system.md) 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](https://handlebarsjs.com) template language. ## Ad Blockers and Web-based Personalization Some of your web users have enabled browser extensions that block ads on the websites that they visit. An ad blocker that is set to be highly restrictive can also block personalized experiences. In addition to preventing ads, web users can configure their ad blocker to prevent data collection, including behavioral data. Users who have opted out of data collection have effectively opted out of your personalization efforts. A highly restrictive ad blocker can block client-side code associated with a web integration, preventing users from receiving recommendations or other personalized experiences. If you want to reach these users with personalization, consider a server-side implementation instead. For a server-side implementation, the Event API can capture most of the same information. One exception is the time a user spends on a page. Depending on your situation, a server-side implementation can be more complex than a web integration solution, so consider the tradeoffs before deciding which approach to use. :::note Ad blockers affect client-side implementations for many personalization and analytics vendors, not just web integrations that use the Marketing Cloud Personalization module of the Salesforce Interactions SDK. :::