Salesforce CDP Web SDK

The Salesforce CDP Web SDK is a low-level API that you can use to configure your website to send events to Salesforce CDP. The process involves configuring your website to collect and submit both customer engagement and user profile data to the Salesforce CDP application. The built-in consent management system ensures that you only collect data from users that choose to allow it. You can make most of these calls from within the Salesforce CDP application interface, or you can call these methods externally using your tenant-specific endpoint.

A newer version of the Web SDK is available. If you have not already implemented the Salesforce CDP Web SDK version, we recommend implementing the latest Salesforce Interactions SDK version.

Important

Prerequisites

To use Salesforce CDP Web SDK, create a Salesforce data source connector. Log into Salesforce CDP and set up a web connector. For additional setup information, see the Salesforce CDP Implementation Guide.

Use the Source ID and tenant-specific endpoint from your website connector to initialize the Salesforce CDP Web SDK.

Download the SDK

Download the source for the Salesforce CDP Web SDK from:

Salesforce CDP Web SDK

Configuring the SDK

The Web SDK consumes this configuration object to automatically generate and assigns event listeners to the related DOM elements. The configuration object structure has several attributes as indicated. All of the attributes except client are optional.

Configuring the SDK: Client Parameters

Setting	Type	Description
appSourceId	String	Required. Obtain this value from your Salesforce admin.
beaconEndpoint	String	Required. Use this structure .
authEndpoint	String	Use this structure .
deviceId	String	Can also be defined in the client configuration, otherwise the identifier created and managed by the SDK is used.
sessionId	String	Is automatically populated by Web SDK.
consentEventTypeName	String	Sets the name of the Consent Event Type. The default name `consentLog` works for most configurations.
retryAttempts	Integer	Is the number of retry attempts if there are failing sending events to the beacon service.
retryDelayMS	Integer	Is the delay duration between retry attempts, milliseconds, if there are failing sending events to the beacon service.
automaticallyTrackNavigationEvents	Boolean	Enable this flag so the Web SDK automatically tracks the user page navigation events and captures `document.location.hash` and `document.location.pathname`.

Configuring the SDK: Signals

Signals are the primary part of the configuration object that the Web SDK engine uses to assign the event listeners to the appropriate DOM element on the page. Signals are the primary piece of the configuration that must be updated after initialization. The signal name, schema, and category are required fields.

Calling CDP.configure method forces all registered signals on the page to be removed before the new set of signals is registered.

Note

Configuring the SDK: Signal Mapping

The mapping field for a registered signal is used to capture data from a web page and map it to the fields in the target schema set on the signal. There are two supported mapping configurations:

Page

A page mapping captures the text value of the element that matches its selector and uses that as the value for the schema event field. The scope value controls which element in the DOM is to execute the selector query. A value of event indicates the element that triggered the signal to be captured. Any other value indicates to begin at the document root.
Data

A data mapping captures the value returned by a data provider. A data provider returns a JavaScript object and the attribute value is used to map a target attribute of that object to a schema event field.

Configuring the SDK: Selectors

Every referenced selector in signal is defined here. Each selector can return one or more DOM elements. There are three types of selectors supported by the Web SDK:

Selectors can be composed of a CSS selector only, defining the path to a DOM element.
Selectors can be composed of a CSS selector and the text attribute of the last element in the path.
Custom JavaScript can be written to implement any unique cases where a CSS selector and text matching does not provide the required functionality.

Configuring the SDK: Schemas

Export your schemas and load them into the SDK.

Configuring the SDK: Data Providers

Data providers represent information that cannot be captured directly from on-screen elements. They are functions that return JavaScript objects from a data layer. The function passes a domEvent parameter that contains the event that triggered this signal to be processed.

Sample Configuration Object

Initializing the SDK

The first step in the lifecycle of the SDK on a page is for it to be initialized. This initialization is where parameters, like the Source ID from the Website Connector, is set to the appSourceId, and the auth and beacon endpoints, crafted from the tenant-specific endpoint, are passed into the SDK.

CDP.initialize(CONFIG) - configures the SDK on initial load, client configuration required
CDP.register(CONFIG) - updates, creates, and overrides configuration parameters

Grab Parameters from the Url

A common operation for user tracking code within a website is to grab the value from query parameters that were passed in the URL. The Salesforce CDP Web SDK includes the following get function that grabs parameters from a web address.

Send Events

Sending signals from your website back to Salesforce CDP is the primary function of the Salesforce CDP Web SDK. The sendEvent() method hides most of the behind-the-scenes complexity and allows you to focus on collecting the data you want to send, without dealing with the mechanics of authentication, building payloads, and managing connections. Your send events must match your schema.

In this example, a product view engagement event is being sent. The product data can come from the DOM, data objects, URL parameters, or any combination of those sources. The required fields for all Salesforce CDP events are populated by the SDK and combined with the provided event data.

By default, the SDK sends events with GET, but if the event payload exceeds 1024 characters a POST with the content type of application/x-www-form-urlencoded is performed instead.

Manage Consent

The Salesforce CDP Web SDK doesn’t persist consent settings across sessions. Pass consent settings for each site visitor. This configuration allows the SDK to integrate easily with existing consent management solutions on your website.

Use these functions in callbacks from your consent management system. The cookie stored by the SDK can't be used to manage consent for your website. The SDK only checks if consent has been granted before sending events.

This call grants consent to the SDK to allow events to signal triggered actions. It sends the CDP.consentOptIn(); event and creates a cookie signifying the user opted in. On subsequent page loads, the presence of this cookie allows events to begin transmitting immediately.

This call removes consent, stops events from being sent. The cookie is removed and events stop emitting immediately.

Customer Data Platform Developer Guide