1. Home
  2. Docs
  3. Developer Docs
  4. eCommerce API

eCommerce API

Orders and eCommerce Events

The e Commerce interface is available to you to record e Commerce events such as product viewed, product placed in the shopping cart, product added to watch list, product ordered.

Functionality of the eCommerce API

The eCommerce API is a JavaScript interface. It can receive various events that a customer triggers in an online shop. This can be done in the classic way per page view or event-driven. The data transmitted consists of information about the products, shopping carts and orders. With the data collected in this way, you can e.g. determine how many shopping carts were left or which products were looked at particularly often.

The data transmission can take place at the actual time of the customer action, for example when the customer puts the product in the shopping cart, or later, e.g. in the case of a submitted form. Here the event is only sent when the customer has reached the following page. In an asynchronous environment it is also possible to store events and only send them when the Signalize code is loaded. The examples below explain the different ways of adding events.

How to get the eCommerce API

Before using the eCommerce API the Signalize code needs to be included on all of the website pages to be measured.

The interface is activated with the delivery of the signalize code, so you are able to embed the events in the code immediately.

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 signalize when debug mode is activated.

The mode can only be switched on once the signalize code has been fully loaded.

To be able to read the output, developer tools, which are offered by multiple browsers nowadays, can help.

BrowserEntwicklertoolBezugsort
FirefoxEntwicklertoolsIst im Browser integriert
Edge (Internet Explorer)EntwicklertoolsIst im Browser integriert
ChromeEntwicklertoolsIst im Browser integriert
OperaEntwicklertoolsIst im Browser integriert
SafariEntwicklertoolsIst im Browser integriert

Switching on Debug Mode with Configuration Object _etr

Notice:

The configuration object can only be integrated when you use the current signalize code 5.x. The setting only executes when the file e.js has been 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.

<script type="text/javascript" charset="UTF-8">
// Parameterblock
var et_pagename = "__INDEX__"; 
var _etr = { debugMode: true };
</script>
<script id="_etLoader" type="text/javascript" charset="UTF-8" data-block-cookies="true" data-preload-dc="data-preload-dc" data-secure-code="Account Schlüssel 1" src="//static.etracker.com/code/e.js">

Switching on Debug Mode with variable etCommerce.debugMode

Notice:
The variable etCommerce.debugMode must be set after calling the signalize code. Signalize Code 5.x is called by the file e.js.

// einschalten des Debug-Modus
etCommerce.debugMode = true ;

Example of signalize code 5.x etCommerce.debugMode after parameter block and signalize code:

<script type="text/javascript" charset="UTF-8">
// Parameterblock
var et_pagename = "Seitenname";
</script>

<script id="_etLoader" type="text/javascript" charset="UTF-8" data-block-cookies="true" data-preload-dc="data-preload-dc" data-secure-code="Account Schlüssel 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 signalize: “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 Signalize 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 signalize code has loaded completely.

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

FunktionsparameterDatentypBegrenzungBeschreibung
eventstringEs werden nur die von der Schnittstelle definierten Events unterstützt.Name des Events
parameter_1, [parameter_n]variiertSiehe weitere Beschreibung.

Notice:

Parameters in square brackets [ ] are optional parameters.

Example:

// direkter Aufruf
etCommerce.sendEvent('viewProduct', product, 'Warenkorb 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 Signalize.

FunktionsparameterDatentypBegrenzungBeschreibung
attachObjectObjektEs werden nur bestehende JavaScript-Events und Objekt-IDs, die mittels getElementById ermittelt werden, unterstützt.
Der Aufbau des Objekts ist folgendermaßen: {‘Eventname’: [‘Objekt-ID1’, ‘Objekt-ID2’]}
In diesem Objekt sind das JavaScript-Event und die IDs der Webseiten-Objekte enthalten, an welche dieses Event angehängt wird.
eventstringEs werden nur die von der Schnittstelle definierten Events unterstützt.Name des angehängten Events.
parameter_1, [parameter_n]variiertSiehe weitere Beschreibung.

Notice:

Parameters in square brackets [ ] are optional parameters.

Example:

// Verknüpfen des eCommerce Events mit einem JavaScript-Event
etCommerce.attachEvent({'mousedown' : ['viewButton']}, 'viewProduct', product, 'Warenkorb 1');

Possible events

At the moment, different events are supported by the eCommerce API, which are described below.

viewProduct – Product viewed

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

FunktionsparameterDatentypBegrenzungBeschreibung
‘viewProduct’stringNur dieser Name ist zugelassen.Name des Events.
Produkt-ObjektobjectDas Objekt muss der Produkt-Objekt-Beschreibung entsprechen.Ein Produkt-Objekt.

Examples:

// Definition des Produkt-Objekts
var product = { 
id : '3445', 
name : 'Elfrida', 
category : ['Tiere', 'Großwild', 'Giraffen', 'Liebe Giraffen'], 
price : '1723.60', 
currency : 'EUR', 
variants : {'Farbe' : 'gelb', 'Geschlecht' : 'weiblich', 'Figur' : 'dünn'}
};

// direkter Aufruf
etCommerce.sendEvent('viewProduct', product, 'Warenkorb 1') ;

// Als Event angehängt
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.

FunktionsparameterDatentypBegrenzungBeschreibung
‘insertToWatchlist’stringNur dieser Name ist zugelassen.Name des Events.
Produkt-ObjektobjectDas Objekt muss der Produkt-Objekt-Beschreibung entsprechen.Ein Produkt-Objekt.
Anzahlinteger0 – 65 535
Negative Zahlen sind nicht erlaubt.
Die Anzahl der auf die Merkliste gesetzten Produkte.
[Seitenname]stringMaximal 255 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Unterscheidet sich der Sei-tenname von dem Standard, kann dieser Seitenname übergeben werden.

Notice:

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

Examples:

// direkter Aufruf
etCommerce.sendEvent('insertToWatchlist', product, 2);

// Als Event angehängt
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.

FunktionsparameterDatentypBegrenzungBeschreibung
‘removeFromWatchlist’stringNur dieser Name ist zugelassen.Name des Events.
Produkt-ObjektobjectDas Objekt muss der Produkt-Objekt-Beschreibung entsprechen.Ein Produkt-Objekt.
Anzahlinteger0 – 65 535
Negative Zahlen sind nicht erlaubt.
Die Anzahl der entfernten Produkte.
[Seitenname]stringMaximal 255 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Unterscheidet sich der Seitenname von dem Standard, kann dieser Seitenname übergeben werden.

Notice:

Parameters in square brackets [ ] are optional parameters.

Examples:

// direkter Aufruf
etCommerce.sendEvent('removeFromWatchlist', product, 1);

// Als Event angehängt
etCommerce.attachEvent({'mousedown' : ['removeButton']}, 'removeFromWatchlist', product, 1);

insertToBasket – Product placed into basket

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

FunktionsparameterDatentypBegrenzungBeschreibung
‘insertToBasket’stringNur dieser Name ist zugelassen.Name des Events.
Produkt-ObjektobjectDas Objekt muss der Produkt-Objekt-Beschreibung entsprechen.Ein Produkt-Objekt.
Anzahlinteger0 – 65 535
Negative Zahlen sind nicht erlaubt.
Die Anzahl der in den Warenkorb gelegten Produkte.

Examples:

// direkter Aufruf
etCommerce.sendEvent('insertToBasket', product, 2);

// Als Event angehängt
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.

FunktionsparameterDatentypBegrenzungBeschreibung
‘removeFromBasket’stringNur dieser Name ist zugelassen.Name des Events.
Produkt-ObjektobjectDas Objekt muss der Produkt-Objekt-Beschreibung entsprechen.Ein Produkt-Objekt.
Anzahlinteger0 – 65 535
Negative Zahlen sind nicht erlaubt.
Die Anzahl der entfernten Produkte.

Examples:

// direkter Aufruf
etCommerce.sendEvent('removeFromBasket', product, 1);

// Als Event angehängt
etCommerce.attachEvent({'mousedown' : ['removeButton']}, 'removeFromBasket', product, 1);

order – Order

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

FunktionsparameterDatentypBegrenzungBeschreibung
‘order’stringNur dieser Name ist erlaubt.Name des Events.
Bestell-ObjektobjectDas Objekt muss der Bestell-Objekt-Beschreibung entsprechen.Ein Bestell-Objekt.
currencystringMaximal 3 Zeichen lang, Leerzeichen am Anfang und Ende werden entfernt.Die Währung nach ISO 4217, z. B. EUR oder USD.

Examples:

// Definition des Bestell-Objekts
var order = {
orderNumber : 'Bestellnummer 1',
status : 'sale',
orderPrice : '1723.60',
basket : {
  id : 'Warenkorb 1',
  products : [ { product: { id : '3445', name : 'Elfrida', category : ['Tiere', 'Großwild', 'Giraffen', 'Liebe Giraffen'], price : '1723.60', currency : 'EUR', }, quantity : 1 }]
}, 
customerGroup : 'Tierliebhaber', 
deliveryConditions : 'Großer Transport', 
paymentConditions : 'Sofortzahlung'};

// direkter Aufruf
etCommerce.sendEvent('order', order);

// Als Event angehängt
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”.

FunktionsparameterDatentypBegrenzungBeschreibung
‘orderConfirmation’stringNur dieser Name ist zugelassen.Name des Events.
BestellnummerstringMaximal 50 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Die Bestellnummer der Bestellung, für die der Status “Lead“ in “Sale“ übergehen soll.

Examples:

// direkter Aufruf
etCommerce.sendEvent('orderConfirmation', 'Bestellnummer 1');

// Als Event angehängt
etCommerce.attachEvent({'mousedown' :['cancelButton']}, 'orderConfirmation', 'Bestellnummer 1');

orderCancellation – Order cancelled

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

FunktionsparameterDatentypBegrenzungBeschreibung
‘oderCancellation’stringNur dieser Name ist zugelassen.Name des Events.
BestellnummerstringMaximal 50 Zeichen lang, Leerzeichen am Anfang und Ende werden entfernt.Die Bestellnummer der Bestellung, die storniert werden soll.

Examples:

// direkter Aufruf
etCommerce.sendEvent('orderCancellation', 'Bestellnummer 1');

orderPartialCancellation – Order partially cancelled

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

FunktionsparameterDatentypBegrenzungBeschreibung
‘orderPartialCancellation’stringNur dieser Name ist erlaubt.Name des Events.
BestellnummerstringMaximal 50 Zeichen lang, Leerzeichen am Anfang und Ende werden entfernt.Die Bestellnummer der Bestellung, die storniert werden soll.
Produkt-Objektearray of objectsDas Array muss der Produkte-Array-Beschreibung entsprechen.Ein Array, welches aus verschiedenen Produkt-Objekten und deren jeweils zu stornierenden Anzahl besteht.

Examples:

// Definition von Produkt-Objekten
var products = [ { product : { id : '3445', name : 'Elfrida', category : ['Tiere', 'Großwild', 'Giraffen', 'Liebe Giraffen'], price : '1723.60', }, quantity: 1}];
// direkter Aufruf
etCommerce.sendEvent('orderPartialCancellation', 'Bestellnummer 1' , products);
// Als Event angehängt
etCommerce.attachEvent({'mousedown' : ['partialButton']}, 'orderPartialCancellation', 'Bestellnummer 1' , products);

Event objects

The products, baskets and order information are 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.

NameAttributDatentypBegrenzungKommentar
Produkt-IDidstringMaximal 50 Zeichen lang, Leerzeichen am Anfang und Ende werden entfernt.Die Produkt-ID wird von Ihnen festgelegt und ergibt sich z. B. aus Ihrem Warenwirtschaftssystem.
Produkt-NamenamestringMaximal 255 Zeichen lang, Leerzeichen am Anfang und Ende werden entfernt.Der Name des Produktes.
Produkt-Hierarchie (Kategorie)categoryarray of stringsEs können maximal vierstufige Hierarchien abgebildet werden. Das Array oder eine Kategorie kann auch leer sein.
Die Hierarchien können 50 Zeichen lang sein,
Leerzeichen am Anfang und Ende werden entfernt.
Die Produkthierarchie wird in einem Array gespeichert,
z. B.: [‘Monitore’, ”, ‘Flachbildschirme’, ‘LED’].
(Nominal)-PreispricestringMaximal 20 Zeichen lang,
Dezimaltrenner ist ein Punkt. Leerzeichen am Anfang und Ende werden entfernt.
Der Preis des Produktes.
WährungcurrencystringMaximal 3 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Die Währung nach ISO 4217, z. B. EUR oder USD.
VariantenvariantsObject with key/value pairsDas Objekt kann leer sein.
Die Varianten können 50 Zeichen lang sein,
Leerzeichen am Anfang und Ende werden entfernt. Maximal 3 Varianten.
Um verschiedene Varianten eines Produktes zu übergeben,
z. B.: {‘Farbe’: ‘gelb’, ‘Geschlecht’: ‘weiblich’, ‘Figur’: ‘dünn’} .

Example:

// Definition eines Produkt-Objekts
var product = { id : '3445', name : 'Elfrida', category : ['Tiere', 'Großwild', 'Giraffen', 'Liebe Giraffen'], price : '1723.60', currency : 'EUR', variants : {'Farbe' : 'gelb', 'Geschlecht' : 'weiblich', 'Figur' : 'dünn'}};

The Basket Object

With an order, the ordered products are placed into a basket object.

NameAttributDatentypBegrenzungKommentar
Warenkorb-IDidstringMaximal 50 Zeichen lang, Leerzeichen am Anfang und Ende werden entfernt.Die Warenkorb-ID wird von Ihnen festgelegt.
Produkt-Objekteproductsarray of objectsDas Array muss der Produkte-Array-Beschreibung entsprechen (siehe folgende Tabelle).In diesem Array werden die verschiedenen Produkt-Objekte und die bestellte Anzahl hinterlegt.

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.

NameAttributDatentypBegrenzungKommentar
ProduktproductobjectDas Objekt muss der Produkt-Objekt-Beschreibung entsprechen.Das Produkt-Objekt.
Anzahlquantityinteger0 – 65 535
Negative Zahlen sind nicht erlaubt.
Die bestellte/stornierte Anzahl.

Example:

// Definition eines Warenkorb-Objekts mit Produkte-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.

NameAttributDatentypBegrenzungKommentar
BestellnummerorderNumberstringMaximal 50 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Die von Ihnen festgelegte eindeutige Bestellnummer. Mit dieser werden spätere Stornierungen getätigt. Bestellnummern, die sich nicht eindeutig einer Bestellung zuordnen lassen, verfälschen die Daten.
StatusstatusenumEnthält lead, sale, cancellation oder partial_cancellation
BestellwertorderPricestringMaximal 20 Zeichen lang,
Dezimaltrenner ist ein Punkt.
Leerzeichen am Anfang und Ende werden entfernt.
Der Gesamtwert der Bestellung. Er sollte sich möglichst als Summe aus Warenkorbwert und Versandkosten ergeben. Rabatte, Gutscheine oder Sonderkosten durch Zahlungsart o.ä. sollten als Produkt-Objekt erfasst werden.
WährungcurrencystringMaximal 3 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Die Währung der Bestellung nach ISO 4217, z. B. EUR oder USD.
Warenkorbbasketobject of warenkorbDas Objekt muss der Warenkorb-Objekt-Beschreibung entsprechen.Das Warenkorb-Objekt.
[Kundengruppe]customerGroupstringMaximal 50 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Z. B.
Neukunde, Stammkunde, Vielkäufer, VIP.
[Lieferbedingungen]deliveryConditionsstringMaximal 255 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Z. B. Lieferung bis Bordsteinkante, Aufstellung vor Ort, Lieferung an Packstation/Paket-shop/Filiale.
[Zahlungsbedingungen]paymentConditionspaymentConditionsMaximal 255 Zeichen lang,
Leerzeichen am Anfang und Ende werden entfernt.
Z. B. spezielle Zahlungsziele, Skonto, Ratenzahlung.

Notice:

Parameters in square brackets [ ] are optional parameters.

Example:

// Definition eines Bestell-Objekts
var order = { orderNumber : '234', status : 'sale', orderPrice : '5447.2', currency : 'EUR', basket : {Warenkorb-Objekt}, customerGroup : ‘Tierliebhaber’, deliveryConditions : 'Großer Transport', paymentConditions : 'Sofortzahlung'};

Application examples

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

Product page viewed

When opening a product page, the product information should be transferred immediately. 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 Angebot', category : ['TV', 'LCD', '47', 'Special'], price : '1723.60', };
// Produkt gesehen
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, the event “removeFromBasket” must be called. 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 Angebot', 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 by directly clicking on the order button, you need an event “order” that will be attached to “sendOrder”. The data is sent directly via the “sendEvent” function.

Example:

var basket = {id : '3',products : [{ product: { id : '3445', name : 'Elfrida', category : ['Tiere', 'Großwild', 'Giraffen', 'Liebe Giraffen'], price : '1723.60', }, quantity : 1}]};

var order = { orderNumber : '234', status : 'sale', orderPrice : '5447.2', basket : basket, customerGroup : ‘Tierliebhaber’, deliveryConditions : 'Großer Transport', paymentConditions : 'Sofortzahlung'};

etCommerce.attachEvent( {'mousedown' : ['sendOrder']}, 'order', order);