The Emarsys data collection JavaScript API captures the activity and behavior of website visitors. This information is used to enrich your Emarsys contact database with behavior fields, and to generate personalized product recommendations for the Predict solutions.

Contents

• Web Extend and other Emarsys products
• Prerequisites
• General usage of the API
• Where to use WebExtend JavaScript API commands
• Command Reference
  • availabilityZone
  • cart
  • category
  • exclude
  • go
  • include
  • language
  • displayCurrency
  • purchase
  • recommend
  • searchTerm
  • setCustomerId
  • setEmail
  • tag
  • testMode
  • view

Web Extend and other Emarsys products

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

Prerequisites

In order to use the Web Extend 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):

<script type="text/javascript">;
var ScarabQueue = ScarabQueue || [];
(function(id) {
  if (document.getElementById(id)) return;
  var js = document.createElement('script'); js.id = id;
  js.src = '//cdn.scarabresearch.com/js/MERCHANT_ID/scarab-v2.js';
  var fs = document.getElementsByTagName('script')[0];
  fs.parentNode.insertBefore(js, fs);
})('scarab-js-api');
</script>

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 Web Extend 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.

General usage of the API

You interact with the Web Extend 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 Web Extend 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:

ScarabQueue.push(['command1', argument1a, argument1b, ...]);
ScarabQueue.push(['command2', argument2a, argument2b, ...]);
...
ScarabQueue.push(['go']);

Where to use WebExtend JavaScript API commands

Some of our API commands should be included in ALL website pages:

• setEmail or setCustomerId, cart and go.

Other API commands are applicable on specific sections of the online storefront:

• view – On product pages.
• category – On category pages.
• searchTerm – Search results pages.
• purchase – On the checkout confirmation page.

For more details please consult the WebExtends JavaScript API implementation guide.

Command Reference

Below is an alphabetical list of all available commands.

availabilityZone (Predict command)

['availabilityZone', zone]

Set availability zone. Used in conjunction with the recommend command for websites which support localization.

• zone (String) – ID of the availability zone. It should match the locale suffix used in the product catalog.

Placement: Use this command on pages which request product recommendations using the recommend command if your site has multiple availability zones.

cart

['cart', cartItems]

Report the list of items in the visitor’s shopping cart.

• cartItems (Array[Object]) – Cart items (may be empty list). A cart item has the following properties:

   

  • item (String) – Unique ID of item (as it appears in the item field of the product catalog).
  • quantity (Number) – Item quantity.
  • price (Number) – Total payable for the given quantity of items.

Placement: Issue this command on every page (even if the customer’s cart is empty).

See example

category

['category', categoryPath]

Report the category currently browsed by the visitor.

• categoryPath (String): Category path (as it appears in the category field of the product catalog).

Placement: Issue this command on category pages only.

See example

exclude (Predict command)

['exclude', field, comparison, expectation]

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 value against.

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

See examples

go

['go']

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.

See example

include (Predict command)

['include', field, comparison, expectation]

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.

For parameter details, see the exclude command.

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

See example

language (Predict and Discovery command)

['language', code]

Set display language for Discovery, and certain Predict web recommender widgets (e.g. HOME and DEPARTMENT).

• language (String) – The language code, as it appears in the product catalog as the suffix of localized fields. Supported languages are listed in the Discovery documentation.

Placement: Issue this command on all pages of a localized website where Discovery is enabled.

displayCurrency (Discovery command)

['displayCurrency', code]

Set display currency for Discovery.

• displayCurrency (String) – The currency code, as it appears in the product catalog as the suffix of price and msrp fields.

Placement: Issue this command on all pages of a website where Discovery is enabled if the default currency needs to be overriden.

purchase

['purchase', descriptor]

Report a purchase event.

• descriptor (Object) – A description of the purchase cart, with the following properties:
  • orderId (String) -The unique ID of the purchase.
  • items (Array[Object]) – The items purchased. A purchased item has the following properties:
    • item (String) -The unique ID of the item (as it appears in the item field of the product catalog).
    • quantity (Number) – The quantity of this item purchased.
    • price (Number) -The total amount payable for the item, taking into consideration the quantity and any discounts.

Placement: Issue this command on the checkout confirmation page.

See example

recommend (Predict command)

['recommend', settings]

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:

<script type="text/html" id="simple-tmpl">
<![CDATA[
    doT.js template
 ]]>
</script>

See example

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.

The SC object

Inside the template, recommendations can be accessed through the SC variable, which stores product recommendations using the following structure:

• recommender.f (String) – The widget name, same as the logic parameter for the recommend command.
• page.products (Array[Object]) – The recommended items. An item has properties which were specified for it in the product catalog.
• topic (String) – The category path of the recommended items if applicable.

See example

The success handler function will be called when recommendations are returned from the recommendation server. It receives two arguments:

• SC (Object) – The description of the recommendations, as seen above.
• 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.

See example

searchTerm

['searchTerm', term]

Report search terms entered by the visitor.

• term – String – The search term entered by the visitor.

placement: Issue this command on the search results page.

setCustomerId

['setCustomerId', customerId]

Report the id of logged in visitors to identify registered customers of your website. Do not use this command if you issue the setEmail command. setEmail is recommended over setCustomerId.

• customerId (String): unique customer ID.

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

setEmail

['setEmail', email]

Report the email address of logged-in visitor to identify registered visitors of your site. Do not use this command if you issue the setCustomerId command. setEmail is recommended over setCustomerId.

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

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

See example

tag

Note: This feature is currently on Pilot release for a limited number of clients only. If you are interested in participating in the pilot phase, please contact Emarsys Support.

['tag', tag]

Add an arbitrary tag to the current event. The tag is collected and can be accessed later from other Emarsys products.

• tag (String): tag.

Placement: This command can be issued on any page.

testMode

['testMode']

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: please note that testMode also prevents Live Events tool from working. Inspector tool will still work to check JS integration.

See example

view

['view', itemId]

Report a product view.

• itemId (String) – ID of the item (as it appears in the item field of the product catalog).

Placement: Issue this command on product pages.

See example