Логотип Help Portal
  • Начало работы

    Introduction

    • Onboarding overview
    • Project Initiation
    • Email compliance
    • Управление учетной записью

    Данные

    • Oбмена данными
    • Aдаптации данных
    • Web data collection

    Channels

    • Email onboarding
    • Smart Insight
    • Predict
  • Обучающие видео
    • Online Self Learning
    • Начало работы: видео
    • Instructor Led Training
    • Webinars
    • Seminars
  • Руководства пользователя

    Стратегия

    • Персонализация
    • Автоматизация
    • Data Monitoring

    Channels

    • Email
    • Мобильные технологии
    • Web
    • Ads

    Add-ons

    • Smart Insight
    • Predict
    • Рекомендации по вознаграждениям
    • AIM
  • Статьи поддержки

    Новости

    • Что нового в платформе Emarsys?
    • Пилотные функции
    • Статьи о защите конфиденциальности данных и GDPR
    • Release notes - archive

    Support

    • Как я могу получить помощь?
    • Редактирование профиля пользователя
  • |
  • Разработчики
  • Статус системы
Нужна помощь? Отправить запрос
Русский Deutsch English Español Français Türkçe 简体中文
Войти
  • Начиная
  • Web Data Collection
  • 0 Начиная Web Data Collection

Содержимое раздела:

  • Web Extend - Overview
  • Data Collection JavaScript API Reference
  • Web Extend — часто задаваемые вопросы
  • in Emarsys42

    Expand all

    Data Collection JavaScript API Reference

    Updated: 29/10/2018 07:52

    К сожалению, эта страница еще не переведена. Уже совсем скоро вся документация будет доступна вам на родном языке.

    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.

    CONTENTS

    • How this works with other Emarsys products
    • Prerequisites
    • General usage of the API
    • Where to use JavaScript API commands
    • Command Reference
      • availabilityZone
      • cart
      • category
      • displayCurrency
      • exclude
      • go
      • include
      • language
      • purchase
      • recommend
      • The SC Object
      • searchTerm
      • setCustomerId
      • setEmail
      • tag
      • testMode
      • view

    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 to your page. The code snippet you need to insert into your websites HTML is available in your Emarsys Marketing Platform account. To display it, go to Admin > Data Sources and click Show tracking code in the Web Behavior box. The code you will see in the modal window already contains your Merchant ID, so all you need to do is paste it into your websites HTML.

    Make sure to add our tracking code to all pages on your website, immediately before the </head> element. As the scarab-v2.js file is loaded asynchronously, it does not block the rendering of the page or the execution of other JavaScript code.

    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

    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:

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

    Where to use JavaScript API commands

    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:

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

    Command Reference

    Below you can find 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).

    Example:

    category

    ['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 (Discovery command)

    ['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 (Predict command)

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

    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.

    Example:

    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.

    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.

    Example:

    language (Predict and Discovery command)

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

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

    This command should be only issued once for a given purchase. Emarsys does not check the submitted purchases for duplication.

    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>

    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.

    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

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

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

    If you want to use this command, you have to create a new custom data field in your Emarsys account (Admin menu > Field Editor) and call it 'predict last session tags'. You can then implement the 'tag' commands you plan to use, and Web Extend will collect these and write them into contact database the next day.

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

    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.

    Example:

    Была ли эта статья полезной?

    Еще есть вопросы? Отправить запрос
    В начало

    You may also be interested in:

    Похожие статьи

    • Google Tag Manager and Data Collection
    • Внедрение сценариев сбора данных Web Extend
    • Подготовка каталога данных по продуктам
    • Загрузка данных о продажах
    • Mobile Data Collection
    Copyright © 2019 Emarsys eMarketing Systems. All rights reserved
    Legal Notice Privacy Policy Master Services Agreement Anti-spam Policy
    test new search