SAP Emarsys Web Extend Integration using Analytical Tools like Adobe Analytics/Google Analytics

[ayushbhardwaj1901]

1           Web Extend

Web Extend is the Emarsys data collection module, which tracks visitor interactions on the e-com website and processes this input to serve validated data to various Emarsys products (such as Revenue attribution, the Automation Center, Smart Insight and Predict).

1.1          Web Extend Scripts

• Web Extend Scripts are data collection scripts that collect website behavior data of website visitors and synchronizes the collected behavior with the contact behavior fields in the Emarsys contact database. This synchronization happens every few hours. Many Automation Center programs are built on these fields.
• The data collection script JavaScript API is used by Predict to deliver real-time, personalized product recommendations on websites and in emails.
• They feed cleaned and validated product and sales data to Smart Insight to create customer lifecycle scoring.

1.2          Web Extend setup/configuration.

The Web Extend tracking scripts are generally supposed to be placed on the frontend html code of the website directly, however some Tag management solution tools (google analytics, adobe analytics etc) can be used as well since they inject the code of 3’rd party tracking scripts into the website’s code directly. These scripts use data captured by the actions the user perfroms and uses it to trigger certain commands (based on the page on which the visitor is) and sends that data to Emarsys, in real time. All the live data sent through the web extend scripts can be seen through live events tool under predict data sources page.

As per GDPR compliances, the tracking scripts should only trigger when the user has given the consent to be tracked. The web extend scripts are no different, in some cases, the cookie consent can be used for this purpose or a specific pop up or banner can be used to provide the info to the user that they are being tracking and the website should allow the user to opt out from this use case anytime.

The value stored in website’s cookie object can be used as a trigger point for the script as if the website cookie does have tracking cookies under the main the umbrella of the “main” website cookies. For example, if the user has accepted tracking cookies then we may want to look at the key value pairs in our cookie, if the targeting cookie’s value is true then we can trigger web extend scripts, this is one of the ways with which we can trigger these tracking scripts only when the user has given some kind of consent (targeting cookie consent as explained above).

The identification method used by these scripts to uniquely identify visitors on the website can be either the email id or any contact id that the website maintains on their end.

Following are the parameters most frequently captured by the web extend scripts.

1. Products Viewed by the Users
2. Category Pages Viewed by the Users
3. Products added/removed by Users in their carts
4. Purchases made by the Users
5. Searches made by Users (the search term)
6. Web Page details of the user browsed (Page URL, Page Title, Page Category)

1.3          Web Extend Integration Through Adobe Analytics:

Just like any other analytical tracking tool (google analytics etc.), Adobe Analytics also has a datalayer javascript object on the website’s frontend code which can be utilized to get the necessary data that needs to be triggered through web extend commands.

The structure of adobe analytics datalayer present on the websites may differ for different implementations however the core structure remains the same which is that the datalayer object majorly contains a dedicated subobjects that capture different types of data for example, the datalayer can contain these types of objects: -

1. User object: - Contains user specific data (username, email, unique itentifiers etc)
2. Webpage object: - Contains the webpage specific details (Like webpage url, page title, breadcrumbs etc)
3. PLP object (product landing page object): - Contains the details of the product page (product info, SKU info, product category info etc)
4. Cart Object: - Contains the details about the cart (product codes/names, quantity, price etc)
5. Transaction object: - Contains the details about purchases made by the user (most of the times this object gets refreshed based on the most recent purchase)

The trigger point for an event can vary based on the type of web extend implementation it is, on a framework codebase, vanilla javascript, on tracking tool (like AA or Google analytics etc)

In case of an analytical tool like Adobe Analytics, where we have a dedicated datalayer object, the trigger point for web extend commands can be any change in datalayer object or subobjects.

1.4          Emarsys Web Extend Scripts: -

The Emarsys web extend scripts have some boilerplate code by default, which mostly initializes a server side javascript script which has all the necessary details for setting up the API connection with the website and predict.

The server-side script can be accessed through the following CDN URL format: -

https://cdn.scarabresearch.com/js/MERCHANT-ID-HERE/scarab-v2.js

This server-side script also initializes the ScarabQueue object using which we trigger various web extend commands.

This script also has the code to trigger the inspector tool which can be used by appending the #sc_inspector fragment to the URL.

The trigger point for an event can vary based on the type of web extend implementation it is, on a framework codebase, vanilla javascript, on tracking tool.

If the web extend implementation is directly in the framework codebase, then the appropriate components in the framework should have the code for the appropriate commands, for example, the cart component in a website built on any framework will have the cart command in the very same code block which has the logic to update cart on the website and so on.

However, in the case of analytical tool, the trigger point will be datalayer change, hence “if” conditions that check a specific object/subobject change in datalayer will be the trigger point for a specific command. Since the script is supposed to load every single time, an event has happened on the website (that’s generally how analytical tools like Adobe analytics/google analytics inject scripts on the website)

However, in case the website is a single page application which does not reload every single time an event on website happens (like clicks, page navigation etc), then in that case, defining a proper trigger point can be a bit bothersome if the source of truth for web extend scripts for running the commands is the datalayer.

So, one of the approaches that can be adapted in this case can be using the javascript setInterval() method which can be used to check the status of datalayer after every specific duration of time, and if the subobjects in the datalayer that are the source of truth for web extend commands are modified, then the commands can be executed.

A good time interval gap can be anywhere between 500ms to 1s because, predict throws an error called “multiple calls of go command” if the rate at which it receives events from web extend exceeds the rate of 2 events/sec (500ms is the minimum time duration between the events)

Also, making sure we check if the very specific objects that are required by the web extend commands have been modified or not and triggering the commands on the updation of those objects is very important because setInterval fucntion is bit processor intense task due to its nature being repetitive.

Another important thing to do is to make sure to have the script have a proper exception handling mechanism on the web extend commands because whatever may be the source of truth for the information of these commands, its possible that sometimes the data we push into our commands may not come in proper expected format.

For example: --

The cart command expects us to pass a list in the ScarabQueue.push() method: -

ScarabQueue.push(['cart', list])

And the list itself should contain multiple objects containing data in the following format: -

list = [

{

‘item’ :  ‘product code’,

‘price’ : ‘price in base currency’,

‘quantity’ : Product quantity

}

{

‘item’ :  ‘product code of second product’,

‘price’ : ‘price in base currency of second product’,

‘quantity’ : Product quantity of second product

}

……. and so on

]

So, if lets say the “item” value that we get is an empty object (due to it not coming from the data source), then we get an error in predict: -

“Invalid argument in cart: item should not be a NaN”

The similar issue could happen in the purchase command if the arguments passed are empty (or in incorrect datatype format): -

The following exception handling process can be implemented to tackle this issue: -

try{

// web extend commands here

}

catch{

console.log("exception occurred in the script")

ScarabQueue.push(['go']);         

// emptying the ScarabQueue to send the data captured by other commands (that did not throw any exception

}

Necessities for Web Extend Commands to Run: -

1. Currency conversion: -

This step is required to be handles in the web extend script if the websites operates across different regions dealing with different types of currencies across, since Emarsys tenant has a specific base currency (which is set up in the predict), the web extend commands which specifically deal with the “price” of the product (like the cart command and the purchase command), hence the price of a product on the website first needs to be converted into the base currency then it has to be passed as a value in the command.

A simple currency converter logic can be implanted like this: -

function currency_converter(price, country) {

var currencyCode = { 'US': 'USD', 'CA': 'CAD', 'AU': 'AUD', 'NZ': 'NZD', 'JP': 'JPY', 'AT': 'EUR', 'BE': 'EUR', 'CH': 'CHF', 'DE': 'EUR', 'DK': 'EUR', 'GR': 'EUR', 'ES': 'EUR', 'FI': 'EUR', 'FR': 'EUR', 'IE': 'EUR', 'IT': 'EUR', 'LU': 'EUR', 'NL': 'EUR', 'NO': 'NOK', 'PT': 'EUR', 'SE': 'SEK', 'GB': 'GBP', }

var fxRate = { 'USD': 1.0000, 'CAD': 0.7692, 'AUD': 0.6898, 'NZD': 0.6154, 'JPY': 0.0074, 'EUR': 1.0004, 'CHF': 1.0256, 'NOK': 0.0920, 'SEK': 0.0938, 'GBP': 1.1629 }

            return price * fxRate[currencyCode[country]]

        }

The above function takes two parameters “price” and “country” and using these values it returns the price in USD.

The currency code object acts as a mapping object to be used to fetch the appropriate conversion rate from the fxRate variable.

Now we can just call this function right before passing the actual currency as a parameter in purchase or cart commands.

1. The Tag command: - Although Emarsys tag command allows any data or value to be passed as a parameter (any string, object, numbers etc) however even the tag command has a specific format with which if the value is passed in this format, it makes the Emarsys web behavior segmenting very easy because that section already has pre-defined dropdown values as the same as the value it expects us to passed.

For Example: -

UseCase1: - ScarabQueue.push(['tag', tag])

Tag: - a string

Usecase2: - ScarabQueue.push(['tag', tag, attributes])

Tag : - an arbitrary string

Attributes: - an object 

Usecase3: - To use the standard web extend segment functionality through readymade dropdown options of content_pageview, use the following format: -

ScarabQueue.push(['tag', 'content_pageview', { content_category: “category here”, content_url: “URL of the page here, content_title: “title of the page here” }]);

Generally, the content category is stored in the form of breadcrumbs In the datalayer hence that object can be retrieved and passed as a value in content_category

Content URL can be found using document.URL object or if its in the datalayer then it can be retrieved from there as well and can be passed as a value above.

Similarly, the content titile can be retrieved using the document.title properly or form the datalayer.

Web Extend Commands

The following web extend commands are the most commonly used web extend commands: -

1. setCustomerId command: - sets the unique identifier to be sent to Emarsys, any unique ID can be sent through this command (that should be set as the predict unique id in Emarsys account as well) This command is supposed to be triggered on all the webpages of Wellastore.

Note: - This command does not trigger when someone is browsing website anonymously (without signing in)

1. setEmail command: - sets the unique identifier to be sent to Emarsys as the email of the the user that should be set as the predict unique id in Emarsys account as well) This command is supposed to be triggered on all the webpages of Wellastore.

Note: - either this or setCustomerId command should be used on website. Using both can result in errors.

1. Category command: - triggers on all the category webpages of the website, generally uses the data from the navigation breadcrumbs to send category to Emarsys. But this sometimes also depends the way category pages are categorized on the website. The hierarchy sent by this command should match with what is sent in the product catalog.

1. Cart command: - sends the cart information of the visitor on the website. This is one of the most important command that should trigger on all the webpages (even if the user does not make any changes to the cart) because it allows emarsys to track all the cart changes made by the user on the website and this empowers the abandoned cart automations in Emarsys

The following Data is sent to Emarsys about products in Cart of the Visitor

• Product ID
• Product Price (in base currency)
• Product Quantity

1. View command: - This command gets triggered on all the product view pages. It sends the product ID of the product to Emarsys

1. Purchase Command: - This command gets triggered when someone’s purchase is successful on website, This command should trigger on the payment confirmation page,The following information regarding the purchase is sent to Emarsys: -

• Order ID
• Product ID
• Price of the Product (in base currency)
• Quantity of the Product Purchased

1. SearchTerm Command: - This command gets triggered when someone searches for an item on Website through the search bar. The exact term the user entered in the search bar is sent to Emarsys. The data is sent to Emarsys when the search result page opens.

1. Tag Command: - This command is used to send custom data to Emarsys. It can either be triggered on all the webpages or some specific ones as well. Any custom term can be sent into this command which can directly be used in the web behavior segmentaion

1. Go command: - Sends the data collected by the other commands on Website. to Emarsys. Should trigger on all the webpages.