1. Home
  2. Docs
  3. Integration & Setup
  4. Tracking Code & SDKs
  5. Tracking Code Integration
  6. Transferring eCommerce Events

Transferring eCommerce Events

eCommerce Events

By capturing eCommerce events, the entire user journey through an online store can be tracked and broken down to categories and items. In addition to transaction data when an order is completed, eCommerce events also include interactions that take place before a purchase has been made:

  • Product list views
  • Product detail calls
  • Watch list actions
  • Shopping cart actions
  • Orders up to conversion into purchases or cancellations.

If, on the other hand, you only want to measure the transactions themselves, the easiest way to do this is to use parameters in the etracker code.

More information about order parameters can be found here.

eCommerce tracking with etracker Analytics for in-depth analysis of shopping patterns can be implemented in three ways:

  1. Implementation via plugins.
  2. Recording via Google Analytics e-commerce parameters.
  3. Manual integration of etracker eCommerce events.

1. Implementation via Plugins

The special extensions for store systems simplify the implementation. Here you can find the available plugins for the most common store systems.

2. Recording via Google Analytics eCommerce parameter

If you use another store system and, for example, a plugin for Google Analytics e-commerce tracking (GA4 or UA), etracker will take over the measurement by adding a supplement to the etracker code.

However, the measurement is only possible if the e-commerce parameters are directly available in the HTML code and have not been implemented via the Google Tag Manager. The use of Google Analytics is not required for this. The Google Tag can remain present or be removed.

Another requirement is that the current etracker code is correctly integrated and supplemented with the data-ecommerce-grabber=”true” data attribute.

The etracker code reads as follows:

<!-- Copyright (c) 2000-2021 etracker GmbH. All rights reserved. -->
<!-- This material may not be reproduced, displayed, modified or distributed -->
<!-- without the express prior written permission of the copyright holder. -->
<!-- etracker tracklet 5.0 -->
<script type="text/javascript">
// var et_pagename = "";
// var et_areas = "";
// var et_tval = 0;
// var et_tsale = 0;
// var et_tonr = "";
// var et_basket = "";
</script>
<script data-ecommerce-grabber="true" id="_etLoader" type="text/javascript" charset="UTF-8" data-block-cookies="true" data-secure-code="XXXXXX" src="//code.etracker.com/code/e.js" async></script>
<!-- etracker tracklet 5.0 end -->

The data-secure-code “xxxxxx” has to be replaced by the personal account key.

The following eCommerce events are adopted by etracker:

  • Product seen on a list
  • Product (detail page) viewed
  • Added to shopping cart
  • Removed from shopping cart
  • Product ordered as a lead

Important: If etracker eCommerce events are already recorded via an etracker store plugin or the directly integrated measurement, the function described here should not be used in order to avoid recording the events twice.

3. Manual integration of etracker eCommerce events

The etracker eCommerce API is available for manual integration.

The eCommerce API is a JavaScript interface that is activated when the etracker code is delivered, so that the events can be integrated into the code immediately.

Note: The eCommerce events must not be sent until the etracker code has been fully loaded. To avoid timing problems, the eCommerce event should therefore be delayed and the _etrackerOnReady function should be used to ensure that the etracker code has already been loaded before the eCommerce events are sent:

<script>
function _etrackerOnReady() {
etCommerce.sendEvent('viewProduct', { /* product */ } );
}
</script>

Or the following function if multiple events are to be sent at different places in the code:

<script>
var _etrackerOnReady = typeof _etrackerOnReady === 'undefined' ? [] : _etrackerOnReady;
_etrackerOnReady.push(function() { etCommerce.sendEvent('viewProduct', { /* product1 */ } ) });
</script>
...
<script>
_etrackerOnReady.push(function() { etCommerce.sendEvent('viewProduct', { /* product2 */ } ) });
</script>

Debug Mode

The interface is equipped with a debug mode, which is especially helpful during the eCommerce API installation. When the debug mode is enabled, error messages, events and the call to the etracker interface are displayed in the JavaScript console of the browser.

Please note: Events are not transmitted to etracker while debug mode is enabled. The mode can only be turned on when the etracker code is completely loaded. To be able to read the output, developer tools like those offered by many browsers today are helpful.

The basic report Last Visitors is very helpful for checking changes in live operation. Here you can see in real time whether the events are transferred correctly. If you trigger the events yourself, make sure that the IP blocking or the individual opt-out does not prevent the collection.

Enable debug mode from the console

Debug mode can be enabled directly in the console with the following commands:

_etracker.tools.enableDebug()
_etracker.tools.enableDebugMode()

A config cookie will be set for this session containing the respective setting.

Note: When debug mode is active, the events are not transmitted to etracker, but only reflected in the console.

After a successful test you have to switch off the debug mode with the following commands:

_etracker.tools.disableDebug()
_etracker.tools.disableDebugMode()

Functions of the eCommerce API

The interface has two basic functions to send information to etracker: sendEvent and attachEvent. sendEvent is the direct call to an eCommerce event defined by the interface, which immediately sends the passed values. If the sending should be linked to a specific JavaScript event – e.g. visitor clicks on “in the shopping cart” – the attachEvent function can be used, which attaches the eCommerce event to a desired object on the website. If the tracking code is embedded at the end of the HTML page or loaded asynchronously, there is a possibility to cache events and attaching events to HTML objects. The functions are executed when the tracking code is completely loaded.

sendEvent – Sending Event directly

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.

Example:

// direct call
etCommerce.sendEvent('viewProduct', product, 'basket 1') ;

attachEvent – Connecting Event to Object

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.

Example:

// Direct link of an eCommerce Event with a JavaScript-Event 
etCommerce.attachEvent({'mousedown' : ['viewButton']}, 'viewProduct', product, 'basket 1') ;

Possible Events

Currently the eCommerce API supports nine different events which are described in the following section.

viewProduct – Product (detail page) viewed

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

Example:

// Definition of a product object 
var product = {
  id: '3445',
  name: 'TV 47 Zoll Special Offer',
  price: '1723.60',
  currency: 'EUR',
  category: ['TV', 'LCD', '47', 'Special']
};
function _etrackerOnReady() {  
etCommerce.sendEvent('viewProduct', product);
}

insertToBasket – Product placed into basket

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

Example:

// Definition of a product object 
var product = {
  id: '3445',
  name: 'TV 47 Zoll Special Offer',
  price: '1723.60',
  currency: 'EUR',
  category: ['TV', 'LCD', '47', 'Special']
};
   
etCommerce.sendEvent('insertToBasket', product, 3);

removeFromBasket – Product removed from basket

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

Example:

// Definition of a product object 
var product = {
  id: '3445',
  name: 'TV 47 Zoll Special Offer',
  price: '1723.60',
  currency: 'EUR',
  category: ['TV', 'LCD', '47', 'Special']
};
   
etCommerce.sendEvent('removeFromBasket', product, 2);

insertToWatchlist – Product added to the watchlist

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

Note: Parameters in square brackets [ ] are optional parameters. The basket ID is not yet shown in reports.

Example:

// Definition of a product object 
var product = {
  id: '3445',
  name: 'TV 47 Zoll Special Offer',
  price: '1723.60',
  currency: 'EUR',
  category: ['TV', 'LCD', '47', 'Special']
};
   
etCommerce.sendEvent('insertToWatchlist', product, 3);

removeFromWatchlist – Product removed from watchlist

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

Note: Parameters in square brackets [ ] are optional parameters.

Example:

// Definition of a product object 
var product = {
  id: '3445',
  name: 'TV 47 Zoll Special Offer',
  price: '1723.60',
  currency: 'EUR',
  category: ['TV', 'LCD', '47', 'Special']
};
   
etCommerce.sendEvent('removeFromWatchlist', product, 2);

viewProductList – Product seen on a list

This event can be sent when the customer is on a product list.

FunktionsparameterDatentypBegrenzungBeschreibung
'viewProductList'stringNur dieser Name ist zugelassen
Produktliste-ObjektobjectDas Objekt muss der Produktliste-Objekt-Beschreibung entsprechen.Ein Produkliste-Object

Note: Parameters in square brackets [ ] are optional parameters.

Example:

// Definition of a product list object
var productList = {
  listType: 'genericlist',
  products: [
    {
      id: '12345',
      name: 'Silver',
      price: '0',
      currency: 'EUR',
      category: ['Electricity', 'Private customers']
    },
    {
      id: '12346',
      name: 'Gold',
      price: '0',
      currency: 'EUR',
      category: ['Electricity', 'Private customers'],
    },
    {
      id: '12347',
      name: 'Platinum',
      price: '0',
      currency: 'EUR',   
      category: ['Electricity', 'Private customers']
    }
  ]
};
 function _etrackerOnReady() { 
etCommerce.sendEvent('viewProductList', productList) ;
}

order – Order

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

Example:

// Definition of order object
var order = {
  orderNumber: 'Order number 1',
  status: 'sale',
  orderPrice: '1301.30',
  currency: 'EUR',
  basket: {
    id: 'Basket 1',
    products: [
      {
        product: {
          id: '3445',
          name: 'Elfrida',
          price: '200.20',
          currency: 'EUR',
          category: ['Tiere', 'Großwild', 'Giraffen', 'Liebe Giraffen']
        },
        quantity: 2
      }
      ,
      {
        product: {
          id: '3446',
          name: 'Berta',
          price: '300.30',
          currency: 'EUR',
          category: ['Tiere', 'Haustiere', 'Kühe', 'Milchkühe']
        },
        quantity: 3
      }
    ]
  },
  customerGroup: 'Tierliebhaber',
  deliveryConditions: 'Großer Transport',
  paymentConditions: 'Sofortzahlung'
};
 function _etrackerOnReady() { 
etCommerce.sendEvent('order', order);
}

orderCancellation – Order cancelled

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

Example:

etCommerce.sendEvent('orderCancellation', 'Order number 1') ;

Event Objects

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.

The Product Object

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
(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
[Coupon]couponstringMaximum 50 characters long,
spaces at the start and end are removed
The name of the product coupon
[Discount]discountstringMaximum 20 characters long,
spaces at the start and end are removed
The discount given. This is deducted from the price of the product in the report.
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’]
VariantsvariantsObject with key/value pairs The object can be empty.
The variants can be 50 characters long,
Spaces at the beginning and end are removed. Maximum 5 variants. If the keys are not explicitly named 'var1' - 'var5', the assignment to the product variant attributes is made according to the alphabetical sorting of the keys.
To transmitt different variants of a product.
e.g. {'var1': 'yellow', 'var2': 'XL'}

{'size': 'XL', 'color': 'yellow'} corresponds after sorting the keys then {'var1': 'yellow', 'var2': 'XL'}

Examples:

var product = {
  id: '3445',
  name: 'TV 47 Zoll Special Offer', 
  price: '1723.60',
  currency: 'EUR',
  category: ['TV', 'OLED', '47', 'Special'],
  variants: {'var1': 'matt'}
};

The Product List Object

In a viewProductList event, the product list is passed with this object.

NameAttributDatentypBegrenzungKommentar
Listentyp listTypeenumNur die Werte 'categorylist', 'searchlist' und 'genericlist' sind zugelassenDer Default ist genericlist, wenn kein oder ein ungültiger Wert übergeben wird
Produkt-Objekteproductsarray of objectsDie Einträge des Arrays müssen der Produkt-Objekt-Beschreibung entsprechenIn diesem Array werden die verschiedenen Produkt-Objekte hinterlegt. Die Position im Array entspricht der Position in der Produktliste.

The Basket Object

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 Object

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

The Order Object

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
[Coupon]couponstringMaximum 50 characters long,
Spaces at the start and end are removed
The name of the order coupon
[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.

Examples of use

The application areas make clear how the different events for certain actions can be sent to etracker from the website.

Product page viewed

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 Zoll Special Offer', 
    category : ['TV', 'LCD', '47', 'Special'], 
    price      : '1723.60', 
    currency  : 'EUR'
};
   
// Produkt gesehen 
function _etrackerOnReady() {
etCommerce.sendEvent('viewProduct', et_Commerce_product, et_Commerce_basketId);
}

Product placed into basket

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 Zoll Special Angebot', 
 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);

Removing a Product from the Basket

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 Zoll Special Angebot', 
 category : ['TV', 'LCD', '47', 'Special'], 
 price : '1723.60', 
 currency : 'EUR'
};
etCommerce.sendEvent('removeFromBasket', et_Commerce_product, 1, et_Commerce_basketId);

Sending an order with a click

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

Articles