Data Collection JavaScript API Reference

The Emarsys JavaScript API (also sometimes referred to as Web Extend) is a data collection system that captures the activity and behavior of website visitors. This information is used to enrich your Emarsys contact database with web behavior fields, and to generate personalized product recommendations for the Predict solutions.

How this works with other Emarsys products

The Emarsys JavaScript API may be used for both data collection and for obtaining Predict product recommendations. In addition, Discovery is also enabled using this API. API features which are related to other Emarsys products than (such as Predict and Discovery) are marked as such in the Command Reference.

Prerequisites

In order to use the JavaScript API, you have to load the scarab-v2.js JavaScript source in your page using the following snippet (replace MERCHANT_ID with the merchant ID received during registration):

It is strongly recommended to place this snippet immediately before the </head> element, but at least before any JavaScript code that is intended to work with the JavaScript API. Loading of scarab-v2.js is asynchronous, so it does not block rendering of the page or other JavaScript code included in it.

NOTE: always make sure that the JavaScript API is never cached. In most template-based webshop engines cacheing is set on specific paths – always make sure that the templates in which you implement these API commands are never in a cached path, as this will cause the API to report erroneous data.

If your web store has a template-based engine, make sure that the template files containing the dynamic data collection scripts are excluded from any caching mechanism you are using, as caching will break their operation.

General usage of the API

You interact with the JavaScript API through so called commands. Commands are represented by arrays whose first element is the command name, and subsequent elements (if any) correspond to the parameters of the command.

The JavaScript API collects commands issued by the JavaScript running on your website and stores them for later execution in the global ScarabQueue JavaScript object. To add a command to ScarabQueue, invoke its push method. Actual execution is initiated only when the special go command (having no parameters) is added to the queue; after execution is completed, the queue will be empty. In other words, usage of the API follow the pattern below:

Add exclusion criterion for recommended items; more than one criteria can be specified by multiple exclude commands. An item is not recommended if it satisfies all exclusion criteria. Always used in conjunction with the recommend command.

field (String): name of the product catalog field whose value will be checked by the criterion.

comparison (String): comparison operator, have to be one of:

is – field value should be equal to expectation, where expectation is a String.

in – field value is contained in the expectation, where expectation is an Array[String].

has – field value (a | separated list) contains expectation, where expectation is a String.

overlaps – field value (a | separated list) has at least one element common with expectation, where expectation is an Array[String].

expectation (String or Array[String]: the value or list of values to compare valueagainst.

Placement: Issue this command on pages which use the recommend command.

Execute commands in the queue, that is, send them to the recommender service for processing.

Placement: go should be issued exactly once on every page of the website. It is considered a best practice to issue the go command immediately before the HTML documents’ </body>element. This way, javascript executing on the page can issue commands which are queued for evaluation and executed at once when the page is finished loading.

Add inclusion criterion for recommended items; more than one criteria can be specified by multiple include commands. An item is recommended only if it satisfies all criteria. Always used in conjunction with the recommend command.

Request recommendations (note that it’s possible to request multiple types of recommendations on a single page by issuing this command several times with different parameters).

settings (Object) – The parameters of the recommendation request, it has the following properties:

containerId (String) – The ID of the DOM element where the recommendations are to be rendered. The element must be present in the DOM at the time when the command is issued.

logic (String) – The name of the recommendation widget to use.

limit (Number, optional) – The number of items to recommend; the default value is 5.

templateId (String, optional) -the ID of the DOM element containing the custom template which should be used to render recommendations.

templateStr (String, optional) – The custom template to be used to render recommendations. Not used if templateId is specified.

baseline (Array[String], optional) – The IDs of items recommended by a base (non-Predict) recommendation service. Used when comparing the performance of the Predict recommender to another one.

success (function(SC, render), optional) The success handler callback function, see later. SC is an object containing product recommendation information, render is the javascript function to be called which displays the recommendations.

Placement: Issue this command on any page where recommendations are to be displayed.

If a custom template is used, it should be written using the doT.js template language, for further details, see its documentation. You can either provide the template text directly in the templateStr property, or place it in a script element (with its type set to text/html) and specify the element ID in templateId, like so:

The attribute data-scarabitem must be present on one of the HTML elements containing an item for Predict to be able to track clicks on recommended items. Its value should be the unique item ID (see the item field of the product catalog).

Note that if you want to provide buttons for users to request more recommendations or revisit the set of previously recommended items, set the class of the HTML elements corresponding to these buttons to scarab-next and scarab-prev, respectively. In case the navigation operation cannot be carried out (e.g. there are no more recommendations or there is no previous recommendation to go back to), the scarab-disabled-button class will be added to the given HTML element.

render (function()) – Functions without arguments, which should be called before the success handler function returns. This function is responsible for displaying the recommendations stored in recommendations.

Inside the success handler, you can freely modify or extend the content of SC, which will be passed unchanged to the custom template, if it exists.

Report the email address of known visitors. Known visitors incude users who are logged in, but also any interaction point where the email address is entered by visitor and recorded into Emarsys Contact DB, such as newsletter subscriptions, guest purchases.

email (String): visitor’s e-mail address.

Note: This command is the default identification option, to which setCustomerId is an alternative. Do not mix usage of these two commands.

Placement: Issue this (or the setCustomerId) command on every page if the visitor is logged in or identified.

Disables logging for all commands contained in the current ScarabQueue JavaScript object. In effect, this will prevent data-collection events from being recorded.

Placement: Use testMode command on your staging/test site to avoid test traffic from interfering with your live website data-collection (for example to prevent purchases on the test site from showing up in Site Traffic statistics).

Note that testMode also prevents the Live Events tool from working. The Inspector tool will still work, you can use it for checking your JS integration.