Embedded Files
The content describes how to use Custom Events within the Salesforce Interactions SDK and the Personalization module to track and respond to specific interactions on a website. These Custom Events are useful for triggering specific actions or logging information when certain events occur in the context of personalization and user interaction tracking.
Understanding the Code with an Example
Understanding the Code with an Example
Imagine you are running a personalized marketing campaign on your website, like Amazon does when showing personalized product recommendations. You want to track when a specific stat, such as an "Impression" (when a user views a recommended product), is logged and then perform an action (e.g., log this to the console, trigger another event, etc.).
Here’s a breakdown of how this works:
Custom Events in Salesforce Interactions SDK
Custom Events: These are predefined events in the SDK that you can listen for using event listeners. When these events are triggered, they provide specific details about what happened (e.g., an event was sent, or a stat was logged).
Namespaces: The code provided includes different namespaces (SalesforceInteractions, SalesforceInteractions.mcis, Evergage), each with its own set of Custom Events.
Example of Using Custom Events: Tracking an Impression Stat
Let’s break down the code example:
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnStatSend, (domEvent) => {
console.log(domEvent.detail.campaignStat.stat); // Logs "Impression"
});
const stat = {
experienceId: "test",
control: false,
stat: "Impression",
};
SalesforceInteractions.mcis.sendStat({ campaignStats: [stat] });
How This Works
How This Works
Event Listener:
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnStatSend, callback) sets up an event listener that listens for the OnStatSend Custom Event.
When the OnStatSend event is triggered, it runs the callback function, which logs the specific stat ("Impression") to the console.
Creating a Stat:
The stat object is created with properties like experienceId (a unique ID for the experience), control (indicating whether this is a control group stat), and stat (the specific stat being tracked, here "Impression").
Sending the Stat:
SalesforceInteractions.mcis.sendStat({ campaignStats: [stat] }) sends the stat to the Salesforce system. This action triggers the OnStatSend Custom Event.
Triggering the Event:
Once the stat is sent, the OnStatSend event is automatically triggered, and the event listener catches it. The listener then logs the "Impression" stat to the console.
Key Custom Events and Their Usage
Key Custom Events and Their Usage
1. OnEventResponse
When it's Triggered: This event (mcis:onEventResponse or evergage:onEventResponse) is triggered whenever an Event API request returns a response.
Purpose: It's used to capture the response of an action event and the associated campaign data.
Event Details:
response: Contains the ActionEventResponse, which includes campaign responses and any errors.
actionEvent: The original event that was sent, containing user information, interaction details, etc.
Example Usage:
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnEventResponse, (domEvent) => {
console.log(domEvent.detail.response.campaignResponses);
});
2. OnEventSend
When it's Triggered: Before an event is sent to Personalization (mcis:onBeforeEventSend or evergage:onEventSend).
Purpose: Allows you to inspect or modify the event before it's sent, and can be used to prevent the event from being sent.
Event Details:
actionEvent: Contains details about the event, such as user data, interaction data, etc.
Example Usage (Prevent Event):
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnBeforeEventSend, (event) => {
event.preventDefault(); // Prevents the event from being sent
});
3. OnException
When it's Triggered: When an operation fails (interactions:onException or evergage:onException).
Purpose: Useful for debugging or logging errors that occur during the interaction.
Event Details:
error: Contains error information, like the stack trace.
context: Describes where the error occurred.
Example Usage:
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnException, (domEvent) => {
console.error(`Error in context ${domEvent.detail.context}:`, domEvent.detail.error);
});
4. OnInit
When it's Triggered: When the Personalization module initializes (mcis:onInit or evergage:onInit).
Purpose: Helps with debugging, particularly in Single-Page Applications (SPAs), where you might need to reinitialize without a full page reload.
Event Details:
beaconConfig: Contains internal configuration details for the Web SDK.
Example Usage:
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnInit, (domEvent) => {
console.log('SDK Initialized with config:', domEvent.detail.beaconConfig);
});
5. OnShutDown
When it's Triggered: When the Web SDK is shut down (interactions:onShutDown or evergage:onShutDown).
Purpose: To perform any cleanup or logging when the SDK shuts down.
Event Details:
message: A message indicating the shutdown reason.
Example Usage:
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnShutDown, (domEvent) => {
console.log('SDK Shutdown:', domEvent.detail.message);
});
6. OnClearCookie
When it's Triggered: This is a custom event that can be manually dispatched to clear cookies set by the Web SDK.
Purpose: To instruct the SDK to clear cookies, useful for managing user sessions or privacy compliance.
Event Details:
options: Contains the domain details for which cookies should be cleared.
Example Usage:
document.dispatchEvent(new CustomEvent(SalesforceInteractions.mcis.CustomEvents.OnClearCookie, {
detail: {
options: {
domain: 'example.com'
}
}
}));
Putting It All Together
Putting It All Together
These events allow developers to tap into the lifecycle of the Salesforce Interactions SDK and Evergage, providing powerful customization and integration points. For instance, you can:
Track and log responses from campaigns (OnEventResponse).
Cancel or modify events before they are sent (OnEventSend).
Handle errors gracefully by capturing exceptions (OnException).
Initialize or shutdown operations cleanly in SPAs or other complex environments (OnInit, OnShutDown).
Manage cookies to ensure user privacy and session management (OnClearCookie).
By leveraging these events, developers can ensure that their web personalization implementations are robust, customizable, and responsive to user and system interactions.
Clientside Code setup
Clientside Code setup
(function () {
function apply(context, template) {
const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);
return Evergage.DisplayUtils
.pageElementLoaded(contentZoneSelector)
.then((element) => {
const html = template(context);
Evergage.cashDom(element).html(html);
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnStatSend, (domEvent) => {
console.log(domEvent.detail); // will log "Impression" after the `sendStat` call below
});
document.addEventListener(SalesforceInteractions.mcis.CustomEvents.OnEventResponse, (domEvent) => {
console.log('OnEventResponse: ',domEvent.detail);
});
});
}
function reset(context, template) {
Evergage.cashDom("#evg-new-template").remove();
}
function control(context) {
const contentZoneSelector = Evergage.getContentZoneSelector(context.contentZone);
return Evergage.DisplayUtils
.pageElementLoaded(contentZoneSelector)
.then((element) => {
Evergage.cashDom(element).attr({
"data-evg-campaign-id": context.campaign,
"data-evg-experience-id": context.experience,
"data-evg-user-group": context.userGroup
});
});
}
registerTemplate({
apply: apply,
reset: reset,
control: control
});
})();
Page updated
Google Sites
Report abuse