How this works with other Emarsys products
Make sure to add our tracking code to all pages on your website, immediately before the
</head> element. As the
If you have already implemented the tracking code in your website, you can still display it at any time on the Data Sources page. To do so, find the Account Details box on the bottom right-hand side, and click Tracking code next to your Merchant ID.
General usage of the API
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']);
Some of our API commands should be included in ALL website pages:
- setEmail or setCustomerId to identify known website visitors,
- and cart to report their current cart content.
Other API commands are applicable on specific sections of the online storefront:
Below you can find an alphabetical list of all available commands.
Set availability zone. Used in conjunction with the recommend command for websites which support localization.
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.
Report the list of items in the visitor’s shopping cart.
Array[Object]) – Cart items (may be empty list). A cart item has the following properties:
String) – Unique ID of item (as it appears in the
itemfield of the product catalog).
Number) – Item quantity.
Number) – Total payable for the given quantity of items.
- item (
Placement: Issue this command on every page (even if the customer’s cart is empty).
Report the category currently browsed by the visitor.
String): Category path as it appears in the default
categoryfield 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.
Set display currency for Discovery.
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
String): name of the product catalog field whose value will be checked against the criterion.
String): comparison operator, has to be one of the following:
is – field value is equal to expectation, which is a
in – field value is found in expectation, which is an
has – (applicable only to fields containing multiple values) one of the field values is equal to expectation, which is a
overlaps – (applicable only to fields containing multiple values) one or more of the field values are found in expectation, which is an
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
The comparison only applies to the entire field value and is case sensitive. For example, if you want to exclude the field value
24/7™ Lace Full Coverage Bra you should provide the whole field value exactly as it is spelled, no other strings (such as
24/7™ Lace or
24/7™ lace full coverage bra) will produce a match.
Execute commands in the queue, that is, send them to the recommender service for processing.
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’
['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.
Set display language for Discovery, and certain Predict web recommender widgets (e.g.
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.
Report a purchase event.
Object) – A description of the purchase cart, with the following properties:
String) -The unique ID of the purchase.
Array[Object]) – The items purchased. A purchased item has the following properties:
String) -The unique ID of the item (as it appears in the
itemfield of the product catalog).
Number) – The quantity of this item purchased.
Number) -The total amount payable for the item, taking into consideration the quantity and any discounts.
- item (
- orderId (
Placement: Issue this command on the checkout confirmation page.
This command should be only issued once for a given purchase. Emarsys does not check the submitted purchases for duplication.
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).
Object) – The parameters of the recommendation request, it has the following properties:
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.
String) – The name of the recommendation widget to use.
Number, optional) – The number of items to recommend; the default value is 5.
String, optional) -the ID of the DOM element containing the custom template which should be used to render recommendations.
String, optional) – The custom template to be used to render recommendations. Not used if
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.
- containerId (
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>
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-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:
String) – The widget name, same as the
logicparameter for the recommend command.
Array[Object]) – The recommended items. An item has properties which were specified for it in the product catalog.
String) – The category path of the recommended items if applicable.
The success handler function will be called when recommendations are returned from the recommendation server. It receives two arguments:
Object) – The description of the recommendations, as seen above.
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 search terms entered by the visitor.
String– The search term entered by the visitor.
Placement: Issue this command on the search results page.
Report your inhouse customer ID for known visitors (logged in).
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.
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.
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.
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.
Add an arbitrary tag to the current event. The tag is collected and can be accessed later from other Emarsys products.
Placement: This command can be issued on any page.
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).
testMode also prevents the Live Events tool from working. The Inspector tool will still work, you can use it for checking your JS integration.
Report a product view.
String) – ID of the item (as it appears in the
itemfield of the product catalog).
Placement: Issue this command on product pages.