Salesforce Data Cloud offers various built-in connectors to fetch data from different data sources. To capture engagement data from a website, such as page views, clicks, etc., Data Cloud provides a data capture and collection framework called the Interactions Web SDK. In this blog post, we’ll go over the features of the Web SDK and how you can use them in your websites.
While the Web SDK can be used with any web stack, we’ll be using a sample website built using Lightning Web Runtime (LWR) on Node.js for this blog post. It’s inspired by the E-Bikes sample app and displays a list of products. See the code for the website if you want to try it out locally.
Setting up the connector
The first step in using the Web SDK is to set up the connector via Data Cloud setup. To set up a connector, you need a schema file that describes the different types of events, and the fields for each event type, that you will be capturing on the website. This schema file must be a valid JSON file. Instead of starting from scratch, you can get started with the recommended schema file that Salesforce provides.
The events coming from your website can be categorized into Profile events and Engagement events, which is denoted using the "category" field in the schema definition. The Web SDK comes with several specialized engagement event types, such as Cart, Catalog, and Order, and the recommended schema file already has the definitions for each of these types.
A few important things to note when creating the schema file:
- You can add new event types and fields, but you cannot remove existing ones.
- You can’t update or rename any existing field.
- You cannot update the value of the
"isDataRequired"attribute. - The fields
deviceId,eventId,dateTime,eventType,category, andsessionIdare mandatory for any event type you define.
The Web SDK auto-populates the values of deviceId, eventId, dateTime, and sessionId fields whenever you send an event from your website. Other non-mandatory attributes like pageView, and source-related attributes like sourceUrl, sourceUrlReferrer, sourceChannel etc., are also auto-populated by the SDK.
Once you set up the connector, you’ll also need to set up a data stream to start receiving the data through this connector.
Setting up the data stream
When setting up a data stream based on the connector, you will first be asked to choose the different event types for which you want to receive the data.
A single data stream with the name <connector>-Behavioral events will be created for all the chosen Engagement events. For Profile events, one data stream will be created per profile event chosen. For example, in the below screenshot, notice that different data streams are being created for the profile events Identity, Contact Point Address, and Contact Point Phone, but there’s only one data stream for the engagement events Cart and Cart Item.
Once created, you can update the Behavioral events stream to track more event types by clicking the Add Events button on the Data Stream detail page.
Using the SDK in your website
Each connector that you define will be associated with a unique script URL, which you can find at the very bottom of your connector definition in Setup.
To use the Web SDK in your website, add this script URL to the head tag of your web page. For websites created with LWR, you can add them to the layout template, as we’ve done in the sample website. Once you’ve added the script, you must initialize the SDK using the init() function. You can also optionally set the logging level to help you during development and debugging.
Setting the logging level to 4 or DEBUG ensures that you can see the messages that help you understand what data is being sent from your website to Data Cloud. Once the SDK is initialized, you can start sending events.
Sending events
To send an event, you need to call the sendEvent function. To this function, you can send an interaction object as a parameter that contains the event data. If you are using the specialized engagement events that the SDK provides, then check out the event specification of those events to ensure that you are formatting your request correctly. For example, a Catalog event needs a catalogObject property to be present in the interaction body.
If you have set the appropriate logging level, you can see the data corresponding to the event sent in the browser console logs.
For every event that you send, you can see two log messages.
The first debug message, [DEBUG]: Sent event, shows the event object from your method call with other details that the SDK auto-populates. For example, the source object that includes the Source URL, Referrer URL etc., and the user object that includes a randomly generated ID are auto-populated on the event object. The consent data is added only if a change is detected in the consent status. You will read more about consent and the user object later in this blog post.
The second debug message,[DEBUG]: Sending events, shows the actual body of the events that are being sent from the website to Data Cloud, which are formatted to match the connector’s schema.
Once the events are sent successfully, you can see the data in the website’s behavioral events data lake object (DLO), which is created when you set up the data stream.
Capture consent
Since the Web SDK captures user behavior and interactions, you must collect consent from the user to do so. The Web SDK has a built-in consent mechanism, where events aren’t sent to Data Cloud unless user consent is available. You can set the consent status when initializing the SDK, when sending an event, or when the user manually grants and revokes consent via the UI of your website.
To set consent during initialization, add the consents object to the init method. You would typically do this if consent is already being captured on your website using a different mechanism or tool, and you want to leverage the same consent status in the Web SDK.
If you are building your own consent capture mechanism, as we have in the sample website, you can use the updateConsents method to update the status of the consent. When opting out, the Web SDK immediately sends the consent event to Data Cloud. But when opting in, the Web SDK sends the consent event with the next sendEvent call. Also, consent events are sent to Data Cloud only if there is a change in the consent status.
The consent status is automatically persisted to the first-party cookie, and you can use the methods below to identify if a user has opted in.
Anonymous vs known profiles
The first time the Web SDK is loaded on the browser (init method call), it generates a unique ID called anonymousId, which is persisted to the first-party cookie against which all the events are tracked. This anonymous ID becomes a unique identifier for the user visiting your website on that particular browser.
The anonymousId is automatically added to all the events by the Web SDK. Once the event is translated to the connector’s schema, the anonymousId is mapped to the deviceId field.
Therefore, during data mapping, you must map the deviceID field of your DLOs to the Individual or Party fields on the concerned data model objects (DMO).
Once you know the identity of the user, either because they’ve given their email address or phone number on the website, or because they logged in, you can send an event with the user object and include the attributes of the known user. This way, you are creating an association between the deviceId and the known user.
The eventType attribute on the user object is mandatory, and corresponds to one of the Profile event types in the schema definition of the connector. This attribute ensures that the event data is routed to the Data Stream/DLO created for that Profile event type.
In the below example, we are sending a Profile event of type “Identity,” and we’re including the name and email address of the known user.
Once the event is sent, in the DLO corresponding to the eventType (in this case “Identity”), you can see a row with a deviceId and the corresponding known user’s attributes. If the same known user has used multiple devices or browsers, you’ll see multiple entries for the same known user, each with a different deviceId.
You can now map this Identity DLO to the Individual object and subsequently apply Identity resolutions to have a single view of the user with all their website engagement data.
Sitemap
Sitemap is a feature that allows you to send events from a website without requiring major changes to the website code. This feature will come in handy when you have no control over modifying the individual components in a website, or when embedding the sendEvent function call in every component of the website is not feasible.
A sitemap is a JSON structure containing a bunch of listeners that listen to various DOM events on the website and fire Web SDK events. Once the SDK is initialized, you can use the initSitemap method to initialize the sitemap.
Below is a sitemap for the sample website that sends an event whenever a link in the footer is clicked.
You can also upload the above script in the Sitemap section of the connector itself. Whenever the Web SDK loads on your website, it pulls the latest version of your sitemap from the connector. This gives you the flexibility to update the sitemap without having to redeploy your website for each update.
If your website uses Web Components, then it is important to remember that sitemaps can’t listen to DOM events on elements inside your web component. This is because the internals of a web component are encapsulated from the DOM.
A Chrome Extension called the Salesforce Interactions SDK Launcher is available to help you build and test a sitemap on a customer’s live website.
Conclusion
In this blog post, you learned how to set up your Web SDK and the various features like Consent Management, User Management, and Sitemaps that the Web SDK offers. You can continue your learning by using the sample website code and updating it for your requirements. You can also watch a video explaining the topics covered in this blog post. Be sure to also watch the other great videos in the Data Cloud Decoded series.
In the next blog post, we’ll discuss how you can use Data Cloud to capture events from a website built using Experience Cloud. Stay tuned!
Further resources
- Salesforce recommended Web SDK Schema file
- Web SDK standard event specifications
- Schema mappings from DLO to DMO
- Salesforce Interactions SDK Launcher Chrome plugin to test sitemaps
- Data Cloud Decoded series
- Web SDK Developer Guide
About the author
Aditya Naag Topalli is a 14x Certified Lead Developer Advocate at Salesforce. He empowers and inspires developers in and outside the Salesforce ecosystem through his videos, webinars, blog posts, and open-source contributions, and he also frequently speaks at conferences and events around the world. Follow him on LinkedIn.