Transferring eCommerce Events

  • The eCommerce API is a JavaScript interface. It can receive and transfer different events to etracker which a customer triggered in an online shop. This can be done on each page call or in a way that is controlled by the event. The transferred data consists of information about the products, baskets and orders. Using the data collected this way, you can, for example, determine how many baskets were abandoned or which products were viewed particularly often. The data transfer can be done at the actual point in time of the action by the customer, when, for example, the customer places the product into the basket, or later on when, for example, a form is sent. Here, the event is only sent when the customer has arrived at the following page. In an asynchronous environment, it is also possible to save events and only send them to etracker when the tracking code has loaded. The examples lower down explain the different ways to integrate events.
    The interface is equipped with a debug mode which is particularly helpful when integrating the eCommerce API. When debug mode is activated, error messages, events and the call of the etracker interface are shown in the JavaScript console. The events will not be transferred to etracker when debug mode is activated. The mode can only be switched on once the tracking code has been fully loaded. To be able to read the output, developer tools, which are offered by multiple browsers nowadays, can help.
    BrowserDeveloper toolWhere to find?
    FirefoxFirebughttps://addons.mozilla.org/de/firefox/addon/firebug
    Internet Explorer EntwicklertoolsIs integrated in the browser
    ChromeEntwicklertoolsIs integrated in the browser
    OperaDragonflyIs integrated in the browser
    SafariFirebug litehttp://getfirebug.com/firebuglite
    • Note: The configuration object can only be integrated when you use the current tracking code 4.x. The setting only executes when the file e.js has reloaded. Events sent prior to this will be checked for errors as they are only processed once e.js has loaded. _etr should not be overwritten if it already exists.
      Example:
      <script type="text/javascript" charset="UTF-8"> // Parameterblock var et_pagename = "__INDEX__"; _etr = { debugMode = true; }</script><script id="_etLoader" type="text/javascript" charset="UTF-8" data-preload-dc="data-preload-dc" data-secure-code="Account Key 1" src="//static.etracker.com/code/e.js"></script>
      Note: The variable etCommerce.debugMode must be set after calling the tracking code. Tracking Code 4.x is called by the file e.js.
      // activation of debug modeetCommerce.debugMode = true ;
      Example of tracking code 4.x etCommerce.debugMode after parameter block and etracker code:
      <script type="text/javascript" charset="UTF-8">  // Parameterblock  var et_pagename = "Pagenname"; </script> <script id="_etLoader" type="text/javascript" charset="UTF-8" data-preload-dc="data-preload-dc" data-secure-code="Account Key 1" src="//static.etracker.com/code/e.js"></script> <script type="text/javascript" charset="UTF-8">  var etCommerce.debugMode = true ; </script> 
    The interface has two basic functions for transferring information to etracker: sendEvent and attachEvent. sendEvent is the direct call of an eCommerce event defined by the interface, which sends the transferred values immediately. If sending should be coupled to a specific JavaScript event, e.g. visitor clicks on ‘into the basket’, then the function attachEvent, which attaches the eCommerce event to a desired object on the website, can be used. If the tracking code is integrated at the end of the HTML page or loads asynchronously, then it is possible to save events and the attachment of events to HTML objects to the temporary buffer. The functions are then executed when the etracker tracking code has loaded fully.
    • etCommerce.sendEvent(event, parameter_1, [parameter_n])
      The function sendEvent of the object etCommerce is then called directly in JavaScript. The transferred values are transferred directly to etracker.
      Function parametersData typeLimitationDescription
      eventstringOnly those events defined by the interface are supported (see section 5).unterstützt (siehe Kapitel 5).Name des Events
      parameter_1, [parameter_n] varyingSee further description
      Note: Parameters in square brackets [ ] are optional parameters.
      Beispiel:
      // direct calletCommerce.sendEvent('viewProduct', product, 'basket 1') ;
      etCommerce.attachEvent(attachObject, event, parameter_1, [parameter_n]) With the attachEvent function you can attach an eCommerce Event to every website object which has an ID. This is then triggered by the specified JavaScript event. This way, clicking on the Into the basket button transfers the eCommerce event to etracker.
      Function parametersData typeLimitationDescription
      attachObjectObjectOnly existing JavaScript events and object IDs, which are determined by getElementById, are supported.
      The object structure is as follows: {'Eventname' : ['Object-ID1', ‘Object-ID2’]}
      The JavaScript event and the IDs of the website objects to which this event is attached are contained in this object.
      eventstringOnly those events defined by the interface are supported (see "Possible Events").Name of the attached event
      parameter_1, [parameter_n]varyingSee further description
      Note: Parameters in square brackets [ ] are optional parameters.
      Beispiel:
      // Direct link of an eCommerce Event with a JavaScript-Event etCommerce.attachEvent({'mousedown' : ['viewButton']}, 'viewProduct', product, 'basket 1') ;
    Currently the eCommerce API supports eight different events which are described in the following section.
    • This event can be sent when the customer is on the product page or on a product overview page.
      Function parametersData typeLimitationDescription
      'viewProduct'stringOnly this name is approvedName of the event
      Product objectobjectThe object must correspond to the product object description (see "The Product Object")A product object
      Examples:
      // Definition of a product objekt var productvar product = { id : '3445',  name : 'Elfrida',  category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'],  price : '1723.60',  currency : 'EUR',  variants : {'color' : 'yellow', 'gender' : 'female', 'Figur' : 'thin'}};
      // Direct calletCommerce.sendEvent('viewProduct', product, 'basket 1') ;// Attached as eventetCommerce.attachEvent({'mousedown' : ['button_ view']}, 'viewProduct', product, 'Warenkorb 1') ;
      This event is sent when the customer adds a product to their watchlist.
      Function parametersData typeLimitationDescription
      'insertToWatchlist'stringOnly this name is approvedName of the event
      Product objectobjectThe object must correspond to the product object description
      (see "The Product Object")
      A product object
      Numberinteger0 - 65 535
      Negative numbers are not allowed

      The number of products placed on the watchlist
      [Pagename]stringMaximum 255 characters long,
      Spaces at the start and end are removed
      If the page name is different to the default name, then this page name can be transferred
      Note: Parameters in square brackets [ ] are optional parameters. The basket ID is not yet shown in reports.
      Examples:
      // Direct calletCommerce.sendEvent('insertToWatchlist', product, 2 ;
      // Attached as eventetCommerce.attachEvent({'mousedown' : ['insertButton']}, 'insertToWatchlist', product, 2) ;
      Using this event you can determine which products were removed from the watchlist.
      Function parametersData typeLimitationDescription
      'removeFromWatchlist'stringOnly this name is approvedName of the event
      Product objectobjectThe object must correspond to the product object description (see "The Product Object")A product object
      Numberinteger0 - 65 535
      Negative numbers are not allowed
      The number of removed products
      [pagename]stringMaximum 255 characters long,
      Spaces at the start and end are removed
      If the page name is different to the default name, then this page name can be transferred
      Note: Parameters in square brackets [ ] are optional parameters.
      Examples:
      // Direct calletCommerce.sendEvent('removeFromWatchlist', product, 1) ;
      // Attached as eventetCommerce.attachEvent({'mousedown' : ['removeButton']}, 'removeFromWatchlist', product, 1) ;
      This event is sent when the customer adds a product to their basket.
      Function parametersData typeLimitationDescription
      'insertToBasket'stringOnly this name is approvedName of the event
      Product objectobjectThe object must correspond to the product object description
      (see "The Product Object")
      A product object
      Numberinteger0 - 65 535
      Negative numbers are not allowed
      The number of products placed into the basket
      Examples:
      // Direct calletCommerce.sendEvent('insertToBasket', product, 2) ;
      // Attached as eventetCommerce.attachEvent({'mousedown' : ['insertButton']}, 'insertToBasket', product, 2) ;
      Using this event you can determine which products were removed from the basket.
      Function parametersData typeLimitationDescription
      'removeFromBasket'stringOnly this name is approvedName of the event
      Product objectobjectThe object must correspond to the product object description (see "The Product Object")A product object
      Numberinteger0 - 65 535
      Negative numbers are not allowed
      The number of removed products
      Examples:
      // Direct calletCommerce.sendEvent('removeFromBasket', product, 1) ;
      // Attached as eventetCommerce.attachEvent({'mousedown' : ['removeButton']}, 'removeFromBasket', product, 1) ;
      The event transfers the entire order with all order data as well as well as the basket.
      Function parametersData typeLimitationDescription
      'order'stringOnly this name is allowedName of the event
      Order objectobjectThe object must correspond to the product object description (see "The Order Object")An order object
      currencystringMaximum 3 characters long, spaces at the start and end are removedCurrency according to ISO 4217 e.g.: EUR or USD
      Examples:
      // Definition of order objectvar order = { orderNumber : 'OrderNumber 1', status : 'sale',  orderPrice : '1723.60', basket : { id : 'basket 1', products : [ { product: { id : '3445',  name : 'Elfrida',  category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'],  price : '1723.60', currency : 'EUR',  }, quantity : 1 }]}, customerGroup : 'AnimalLover', deliveryConditions : 'deliveryConditons', paymentConditions : 'BigTransport',};
      // Direct calletCommerce.sendEvent('order', order) ;
      // Attached as EventetCommerce.attachEvent({'mousedown' : ['orderButton']}, 'order', order) ;
      This event is sent when an order including all product items is to be transferred from the status “Lead” to the status “Sale”.
      Function parametersData typeLimitationDescription
      'orderConfirmation'stringOnly this name is approvedName of the event
      Order numberstringMaximum 50 characters long,
      Spaces at the start and end are removed
      The order number of the order for which the status 'Lead' should be transferred to 'Sale'
      Examples:
      // Direct calletCommerce.sendEvent('orderConfirmation', 'Ordernummer 1');
      // Attached as EventetCommerce.attachEvent({'mousedown' :['cancelButton']}, 'orderConfirmation', 'OrderNumber 1') ;
      This event is sent when the customer cancels the entire order.
      Function parametersData typeLimitationDescription
      'oderCancellation'stringOnly this name is approvedName of the event
      Order numberstringMaximum 50 characters long, spaces at the start and end are removedThe order number of the order which should be cancelled
      Examples:
      // Direct calletCommerce.sendEvent('orderCancellation', 'OrderNumber 1') ;
      // Attached as eventetCommerce.attachEvent({'mousedown' : ['cancelButton']}, 'orderCancellation', 'OrderNumber 1') ;
      This event is sent when only individual products of an order are sent.
      Function parametersData typeLimitationDescription
      'orderPartialCancellation'stringOnly this name is allowedName of the event
      Order numberstringMaximum 50 characters long, spaces at the start and end are removedThe order number of the order which should be cancelled
      Product Objectsarray of objectsThe array must correspond to the products array description.An array which consists of different product objects and the respective amount to be cancelled.
      Examples:
      // Definition of product objectsvar products = [ { product : { id : '3445',  name : 'Elfrida',  category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'],  price : '1723.60',  }, quantity: 1}];
      // Direct calletCommerce.sendEvent('orderPartialCancellation', 'OderNumber 1' , products) ;
      // Attached as eventetCommerce.attachEvent({'mousedown' : ['partialButton']}, 'orderPartialCancellation', 'OrderNumber 1' , products) ;
    The product and order information is stored in JavaScript objects. In the following you will find a list of these objects and how they are set up.
    • This object defines a product with the respective attributes.
      NameAttributeData typeLimitationComment
      Product IDidstringMaximum 50 characters long, spaces at the start and end are removedThe product ID is set by you and can be derived from your inventory management system.
      Product namenamestringMaximum 255 characters long, spaces at the start and end are removedThe name of the product
      Product hierarchy (category)categoryarray of stringsFour hierarchy levels are the maximum that can be illustrated. The array or a category can also be empty.
      The hierarchies can be 50 characters long, spaces at the start and end are removed
      The product hierarchy is saved in an array,
      e.g.: [‘monitors’, '', ‘flat screens’, ‘LED’]
      (Nominal) pricepricestringMaximal 20 characters long,
      decimal separator is a dot. Spaces at the start and end are removed
      The price of the product
      CurrencycurrencystringMaximum 3 characters long,
      spaces at the start and end are removed
      Currency according to ISO 4217
      e.g.: EUR or USD
      VariantsvariantsObject with key/value pairs The object can be empty.
      The variants can be 50 characters long,
      spaces at the start and end are removed. Maximum 3 variants
      To transfer different versions of a product.
      e.g.: {‘colour’: ‘yellow’, ‘sex’: ‘female’, ‘figure’: ‘thin’}
      Examples:
      // Definition of Product objectvar product = {    id      : '3445',     name      : 'Elfrida',     category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'],     price      : '1723.60',     currency : 'EUR',     variants : {'colour' : 'yellow', 'gender' : 'female', 'figur' : 'thin'}};
      With an order, the ordered products are placed into a basket object.
      NameAttributeData typeLimitationComment
      Basket IDidstringMaximum 50 characters long, spaces at the start and end are removedYou set the basket ID
      Product Objectsproductsarray of objectsThe array must correspond to the products array description (see following table)The different product objects and the quantity ordered are stored in this array.
      The products array contains one or more objects which then themselves consist of product objects and the respective number. This product array is also used with partial cancellations.
      NameAttributeData typeLimitationComment
      ProductproductobjectThe object must correspond to the product object description.entsprechen.The Product Object
      Numberquantityinteger0 - 65 535
      Negative numbers are not allowed
      The ordered/cancelled amount
      Example:
      // Definition of shopping-basket object with product-Arrayvar basket = { id : '3', products : [ { product: { }, quantity : 2 }, { product: { }, quantity : 1 } ]};
      The object of the order contains all order data and the basket object.
      NameAttributeData typeLimitationComment
      Order numberorderNumberstringMaximum 50 characters long,
      Spaces at the start and end are removed
      The unique order number you set. Future cancellations are actuated with this number. Order numbers, which cannot be assigned explicitly to an order, distort the data.
      StatusstatusenumContains lead, sale, cancellation or partial_cancellation
      Order valueorderPricestringMaximal 20 characters long,
      decimal separator is a dot.
      Spaces at the start and end are removed
      The total order value. As much as possible this should be the sum of the basket value and shipping costs. Discounts, vouchers or special charges due to the payment method, or similar, should be registered as the product object.
      CurrencycurrencystringMaximum 3 characters long,
      Spaces at the start and end are removed
      Currency of the order according to ISO 4217
      e.g.: EUR or USD
      Shopping basketbasketobject of warenkorbThe object must correspond to the basket object description.The Basket Object
      [Customer Group]customerGroupstringMaximum 50 characters long,
      Spaces at the start and end are removed
      e.g.
      - new customer
      - existing customer
      - big buyer
      - VIP
      [Delivery Conditions]deliveryConditionsstringMaximum 255 characters long,
      Spaces at the start and end are removed
      e.g.
      - Delivery to the kerb
      - Setup on site
      - Delivery to the pick-up station/parcel shop/branch
      [Payment Conditions]paymentConditionspaymentConditionsMaximum 255 characters long,
      Spaces at the start and end are removed
      e.g.
      - Special payment targets
      - Cash discount
      - Payment in instalments
      Note: Parameters in square brackets [ ] are optional parameters.
      Example:
      // Definition of an order-objectvar order = { orderNumber : '234', status : 'sale',  orderPrice : '5447.2', currency : 'EUR',  basket : {ShoppingBasket-Object}, customerGroup : ‘Animallovers’, deliveryConditions : 'Big transport', paymentConditions : 'Direct cash',}
    The application areas make clear how the different events for certain actions can be sent to etracker from the website.
    • When opening a product page, the product information should be transferred immediately to etracker. Here, a product object is defined for this. The data is sent directly via the sendEvent function. Example:
      var et_Commerce_basketId = '3';var et_Commerce_product = {    id      : '3445',     name      : 'TV 47 Special offer',     category : [‘TV’, 'LCD', '47', 'Special'],     price      : '1723.60', };  // Product viewed etCommerce.sendEvent('viewProduct', et_Commerce_product, et_Commerce_basketId);
      To record products which are to be placed into the basket (by clicking on the Place in basket button), an event needs to be defined which will be attached to the existing button. Prior to this, a product object which contains the product data needs to be defined. The ID of the button in this case is “ButtonAddToBasket” and the data transfer occurs when the JavaScript event mousedown is triggered. The quantity of products recorded is determined from the ProductQuantity form field saved on the website. Example:
      var et_Commerce_basketId = '3';
      var et_Commerce_product = { id : '3445',  name : 'TV 47 Special offer',  category : [‘TV’, 'LCD', '47', 'Special'],  price : '1723.60', };
      Var et_Commerce_quantity = Number(document.getElementById('ProductQuantity').value) ;
      etCommerce.attachEvent({'mousedown' : ['ButtonAddToBasket']}, 'insertToBasket', et_Commerce_product, et_Commerce_quantity, et_Commerce_basketId);
      To communicate that the customer has removed a product from the basket again, the event removeFromBasket must be called. The data will be sent directly via the sendEvent function. Example:
      var et_Commerce_basketId = '3';
      var et_Commerce_product = { id : '3445',  name : 'TV 47 Special offer',  category : [‘TV’, 'LCD', '47', 'Special'],  price : '1723.60', };
      etCommerce.sendEvent('removeFromBasket', et_Commerce_product, 1, et_Commerce_basketId]);
      To report an order to etracker by directly clicking on the order button, you need an event order that will be attached to sendOrder. The data will be sent directly via the sendEvent function. Example:
      var basket = {id : '3',products : [{ product:  { id : '3445',  name : 'Elfrida',  category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'],  price : '1723.60',  }, quantity : 1}]}
      var order = { orderNumber : '234', status : 'sale',  orderPrice : '5447.2', basket : basket, customerGroup : ‘Animallover’, deliveryConditions : 'Big transport', paymentConditions : 'Direct cash',}
      etCommerce.attachEvent( {'mousedown' : ['sendOrder']}, 'order', order);
    Before you can use etracker Analytics, the eCommerce API and all other etracker products, you need to integrate the current etracker tracking code, which you can find in your etracker account at Settings > Setup/Tracking Code, into all of the pages of your website which you wish to track. In addition, we recommend setting the et_pagename parameter so that the reports can show the individual pages of your website. The interface is activated upon provision of the etracker tracking code so that the events can be integrated immediately into the code.
    Hier sind die Änderungen an der Schnittstelle aufgelistet. Die Anwendungsbeispiele verdeutlichen, wie die verschiedenen Events für ausgewählte Aktionen auf der Webseite an etracker gesendet werden können.
      • Error(s) resolved in debug mode
      • The definition of objects which are triggered by a certain browser event has changed (attachEvent function). From now on, you can define different object IDs in one array using the browser event.
      // Old versionetCommerce.attachEvent({'mousedown' : 'partialButton'}, 'orderPartialCancellation', 'OrderNumber 1' , products);
      // New version with arrayetCommerce.attachEvent({'mousedown' : ['partialButton', ‘partialButton2’]}, 'orderPartialCancellation', 'OrderNumber 1' , products);
      • Typography errors fixed in code examples (“onmousedown” change to “mousedown”).

Need help?
Our friendly, knowledgeable support engineers are here for you.