Data collection JavaScript API reference

['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', 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).

Example:

['category', categoryPath]

Report the category currently browsed by the visitor.

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

Note: if you are using Predict services on a localized website, you will still need to push the default category field value with this command.

Placement: Issue this command on category pages only.

Example:

['displayCurrency', code]

Set display currency for Discovery.

• displayCurrency (String) – The currency code in ISO 4217 format (e.g. eur, usd, huf), as it appears in the product catalog as the suffix of the 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.

['exclude', field, comparison, expectation]

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

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

comparison (String): comparison operator, has to be one of the following:

• is – field value is equal to expectation, which is a String.
• in – field value is found in expectation, which is an Array[String].
• has – (applicable only to fields containing multiple values) one of the field values is equal to expectation, which is a String.
• overlaps – (applicable only to fields containing multiple values) one or more of the field values are found in expectation, which is an Array[String].

expectation (String or Array[String]): the value or list of values to which the field value is compared.

Placement: Issue this command on pages where you use the recommend command.

Example:

['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.

Example:

['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.

Example:

['language', code]

Set display language for Discovery, and certain Predict web recommender widgets (e.g. HOMEand 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.

['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.

Example:

['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:

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.

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.

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.

Example:

['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', customerId]

Report your inhouse customer ID for known visitors (logged in).

• customerId (String): unique customer ID.

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

Placement: Issue this command on every page if the current visitor is identified.

Example:

['setEmail', email]

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.

Example:

['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']

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).

Example:

['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.

Example: