Transferring eCommerce Events

eCommerce Events

By recording eCommerce events, the complete user journey through an online shop can be traced and broken down into categories and articles. eCommerce events include not only the transaction data at order completion, but also the interactions taking place before a purchase:

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

Implementation via Plugins

The eCommerce Event Tracking is already integrated in these plugins:

• xt:Commerce
• shopware
• OXID
• Magento

If you are using another shop system and the Google Enhanced Ecommerce Plugin (directly and not via the Google Tag Manager), etracker takes over the measurement by adding a suffix to the etracker tracking code (see Measuring Google Enhanced Ecommerce Activities with etracker).

The eCommerce JavaScript interface can also be integrated directly into the website and the information can be transferred to etracker with page views and click events.

Measuring Google Enhanced Ecommerce Activities with etracker

If Google’s (Extended) Ecommerce Tracking is integrated in the shop, the data can be collected by etracker if the integration is done directly via the website and not via the data layer of the Google Tag Manager. This simplifies the migration of Google Analytics very much, if not one of the above mentioned plugins is used. The use of Google Analytics is not necessary to do this. The Google Analytics tag can remain in place or be removed.

In addition, it is a prerequisite that the current etracker tracking code is correctly integrated and the data attribute data-ecommerce-grabber=”true” is added.

The tracking code in this case has the following structure:

<! – Copyright (c) 2000-2020 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-respect-dnt="true"
 data-secure-code="ABCDEF" src="//static.etracker.com/code/e.js"></script>
<! – etracker tracklet 5.0 end – >

The data-secure code “ABCDEF” must be replaced by the personal account key.

The following eCommerce events are managed by etracker:

• Product seen on a list
• Product (-detail page) viewed
• Add to shopping cart
• Removed from shopping cart
• Order the product as a lead

Important:

If etracker eCommerce events are already measured via a plugin or the directly integrated API, the function described here should not be used, as the events will be recorded twice.

Integrate etracker eCommerce API into the website The eCommerce API is a JavaScript interface. The interface is activated with the delivery of the etracker tracking code, so that the events can be immediately integrated into the code.

Debug Mode

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.

Switching on Debug Mode with Configuration Object _etr

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>

Switching on Debug Mode with variable etCommerce.debugMode

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 mode
etCommerce.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> 

Functions of the eCommerce API

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.

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.

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

Beispiel:

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

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

Possible Events

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

viewProduct – Product viewed

This event can be sent when the customer is on the product page or on a product overview page.

Examples:

// Definition of a product objekt var product
var product = 
{
 id : '3445', 
 name : 'Elfrida', 
 category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'], 
 price : '1723.60', 
 currency : 'EUR', 
 variants : {'color' : 'yellow', 'gender' : 'female', 'Figur' : 'thin'}
};

// Direct call
etCommerce.sendEvent('viewProduct', product, 'basket 1') ;
// Attached as event
etCommerce.attachEvent({'mousedown' : ['button_ view']}, 'viewProduct', product, 'Warenkorb 1') ;

insertToWatchlist – Product added to the watchlist

This event is sent when the customer adds a product to their watchlist.

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

Examples:

// Direct call
etCommerce.sendEvent('insertToWatchlist', product, 2 ;

// Attached as event
etCommerce.attachEvent({'mousedown' : ['insertButton']}, 'insertToWatchlist', product, 2) ;

removeFromWatchlist – Product removed from watchlist

Using this event you can determine which products were removed from the watchlist.

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

Examples:

// Direct call
etCommerce.sendEvent('removeFromWatchlist', product, 1) ;

// Attached as event
etCommerce.attachEvent({'mousedown' : ['removeButton']}, 'removeFromWatchlist', product, 1) ;

insertToBasket – Product placed into basket

This event is sent when the customer adds a product to their basket.

Examples:

// Direct call
etCommerce.sendEvent('insertToBasket', product, 2) ;

// Attached as event
etCommerce.attachEvent({'mousedown' : ['insertButton']}, 'insertToBasket', product, 2) ;

removeFromBasket – Product removed from basket

Using this event you can determine which products were removed from the basket.

Examples:

// Direct call
etCommerce.sendEvent('removeFromBasket', product, 1) ;

// Attached as event
etCommerce.attachEvent({'mousedown' : ['removeButton']}, 'removeFromBasket', product, 1) ;

order – Order

The event transfers the entire order with all order data as well as well as the basket.

Examples:

// Definition of order object
var 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 call
etCommerce.sendEvent('order', order) ;

// Attached as Event
etCommerce.attachEvent({'mousedown' : ['orderButton']}, 'order', order) ;

orderConfirmation – Order transferred from Status Lead to Status Sale

This event is sent when an order including all product items is to be transferred from the status “Lead” to the status “Sale”.

Examples:

// Direct call
etCommerce.sendEvent('orderConfirmation', 'Ordernummer 1');

// Attached as Event
etCommerce.attachEvent({'mousedown' :['cancelButton']}, 'orderConfirmation', 'OrderNumber 1') ;

orderCancellation – Order cancelled

This event is sent when the customer cancels the entire order.

Examples:

// Direct call
etCommerce.sendEvent('orderCancellation', 'OrderNumber 1') ;

// Attached as event
etCommerce.attachEvent({'mousedown' : ['cancelButton']}, 'orderCancellation', 'OrderNumber 1') ;

orderPartialCancellation – Order partially cancelled

This event is sent when only individual products of an order are sent.

Examples:

// Definition of product objects
var products = [
 {
 product : {
 id : '3445', 
 name : 'Elfrida', 
 category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'], 
 price : '1723.60', 
 },
 quantity: 1
}
];

// Direct call
etCommerce.sendEvent('orderPartialCancellation', 'OderNumber 1' , products) ;

// Attached as event
etCommerce.attachEvent({'mousedown' : ['partialButton']}, 'orderPartialCancellation', 'OrderNumber 1' , products) ;

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.

Examples:

// Definition of Product object
var product = 
{
    id      : '3445', 
    name      : 'Elfrida', 
    category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'], 
    price      : '1723.60', 
    currency : 'EUR', 
    variants : {'colour' : 'yellow', 'gender' : 'female', 'figur' : 'thin'}
};

The Basket Object

With an order, the ordered products are placed into a basket 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.

Example:

// Definition of shopping-basket object with product-Array
var basket = 
{
 id : '3',
 products : [
 {
 product: {
 …
 },
 quantity : 2
 },
 {
 product: {
 …
 },
 quantity : 1
 }
 ]
};

The Order Object

The object of the order contains all order data and the basket object.

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

Example:

// Definition of an order-object
var order = 
{
 orderNumber : '234',
 status : 'sale', 
 orderPrice : '5447.2',
 currency : 'EUR', 
 basket : {ShoppingBasket-Object},
 customerGroup : ‘Animallovers’,
 deliveryConditions : 'Big transport',
 paymentConditions : 'Direct cash',
}

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 Special offer', 
    category : [‘TV’, 'LCD', '47', 'Special'], 
    price      : '1723.60', 
};
 
 
// Product viewed 
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 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);

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 Special offer', 
 category : [‘TV’, 'LCD', '47', 'Special'], 
 price : '1723.60', 
};

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

Access to the eCommerce API

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.

Change log

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.

Version 1.1.1

• 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 version
etCommerce.attachEvent({'mousedown' : 'partialButton'}, 'orderPartialCancellation', 'OrderNumber 1' , products);

// New version with array
etCommerce.attachEvent({'mousedown' : ['partialButton', ‘partialButton2’]}, 'orderPartialCancellation', 'OrderNumber 1' , products);

Version 1.1.3

• Typography errors fixed in code examples (“onmousedown” change to “mousedown”).