eCommerce API

Bestellungen und eCommerce Events

Um eCommerce-Events wie Produkt angesehen, Produkt in den Warenkorb gelegt, Produkt auf Merkliste gesetzt, Produkt bestellt zu erfassen, steht Ihnen die eCommerce-Schnittstelle zur Verfügung.

Funktionalität der eCommerce API

Die eCommerce API ist eine JavaScript-Schnittstelle. Sie kann verschiedene Events, die ein Kunde in einem Online-Shop auslöst, entgegennehmen. Dies kann klassisch pro Seitenaufruf oder auch Event-gesteuert geschehen. Die dabei übertragenen Daten bestehen aus Informationen über die Produkte, Warenkörbe und Bestellungen. Mit den so erfassten Daten können Sie z. B. ermitteln, wie viele Warenkörbe stehengelassen oder welche Produkte besonders häufig angeschaut wurden.

Die Datenübermittlung kann zum tatsächlichen Zeitpunkt der Kundenaktion geschehen, wenn bspw. der Kunde das Produkt in den Warenkorb legt, oder später, z. B. im Fall eines abgesendeten Formulars. Hier wird das Event erst gesendet, wenn der Kunde auf der Folgeseite angelangt ist. In einer asynchronen Umgebung ist es außerdem möglich, Events zu speichern und erst zu senden, wenn der Signalize Code geladen ist. Die Beispiele weiter unten erläutern die verschiedenen Varianten zum Einbau von Events.

Zugang zur eCommerce API

Bevor Sie die eCommerce API einsetzen können, müssen Sie den Signalize Code auf allen zu messenden Seiten der Website einbinden.

Die Schnittstelle ist mit der Auslieferung des Signalize Codes aktiviert, sodass Sie die Events sofort in den Code einbinden können.

Debug-Modus

• Konfigurationsobjekt _etr einschalten
  
• Variable etCommerce.debugMode einschalten
  

Die Schnittstelle ist mit einem Debug-Modus ausgestattet, der besonders während des Einbaus der eCommerce API hilfreich ist. Wenn der Debug-Modus aktiviert ist, werden Fehlermeldungen, Events und der Aufruf der Schnittstelle in der JavaScript-Konsole angezeigt. Die Events werden nicht an übermittelt, wenn der Debug-Modus aktiviert ist.

Der Modus kann erst eingeschaltet werden, wenn der signalize Code komplett geladen ist.

Um die Ausgaben lesen zu können, helfen Entwicklertools wie sie heute von vielen Browsern angeboten werden.

Konfigurationsobjekt _etr einschalten

Hinweis:

Das Konfigurationsobjekt können Sie nur einbauen, wenn Sie den aktuellen Signalize Code 5.x verwenden. Die Einstellung greift erst, wenn die Datei e.js nachgeladen ist. Vorher versendete Events werden aber trotzdem auf Fehler geprüft, da sie erst verarbeitet werden, wenn die e.js geladen ist.

„_etr“ sollte nicht überschrieben werden, falls es bereits existiert.

<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">

Variable etCommerce.debugMode einschalten

Hinweis:
Die Variable etCommerce.debugMode muss nach dem Aufruf des Signalize Codes gesetzt werden. Der Signalize Code 5.x wird durch die Datei e.js aufgerufen.

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

Beispiel für signalize Code 5.x etCommerce.debugMode hinter Parameterblock und 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>

Die Funktionen der eCommerce API

Die Schnittstelle hat zwei grundlegende Funktionen, um Informationen zu übermitteln: “sendEvent“ und “attachEvent“. “sendEvent“ ist der direkte Aufruf eines von der Schnittstelle definierten eCommerce Events, welcher sofort die übergebenen Werte sendet. Soll das Absenden an ein bestimmtes JavaScript Event gekoppelt sein – z. B. Besucher klickt auf “in den Warenkorb“ -, dann kann die Funktion “attachEvent“ verwendet werden, die das eCommerce Event an ein gewünschtes Objekt der Webseite anhängt.

Wenn der signalize Code am Ende der HTML-Seite eingebaut ist oder asynchron geladen wird, gibt es die Möglichkeit, Events und das Anhängen von Events an HTML-Objekte zwischenzuspeichern. Die Funktionen werden dann ausgeführt, wenn der Signalize Code komplett geladen ist.

sendEvent – Event direkt absenden

etCommerce.sendEvent(event, parameter_1, [parameter_n]);

Die Funktion „sendEvent“ des Objekts „etCommerce“ wird im JavaScript direkt aufgerufen. Die übergebenen Werte werden dabei direkt an übermittelt.

Hinweis:

Parameter in eckigen Klammern [ ] sind optionale Parameter.

Beispiel:

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

attachEvent – Event an Objekt anknüpfen

etCommerce.attachEvent(attachObject, event, parameter_1, [parameter_n]);

Mit der Funktion attachEvent können Sie an jedes Webseiten-Objekt, welches eine ID besitzt, ein eCommerce Event anhängen. Dieses wird dann durch das angegebene JavaScript-Event ausgelöst. So kann direkt mit dem Klick auf den Button In den Warenkorb das eCommerce Event an übermittelt werden.

Hinweis:

Parameter in eckigen Klammern [ ] sind optionale Parameter.

Beispiel:

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

Mögliche Events

Gegenwärtig unterstützt die eCommerce API verschiedene Events, die im Folgenden beschrieben werden.

• viewProduct – Produkt gesehen
  
• insertToWatchlist – Produkt zur Merkliste hinzugefügt
  
• removeFromWatchlist – Produkt von Merkliste entfernt
  
• insertToBasket – Produkt in den Warenkorb gelegt
  
• removeFromBasket – Produkt aus dem Warenkorb entfernt
  
• order – Bestellung
  
• orderConfirmation – Bestellung vom Status Lead in den Status Sale transferiert
  
• orderCancellation – Bestellung storniert
  
• orderPartialCancellation – Bestellung teilstorniert
  

viewProduct – Produkt gesehen

Dieses Event kann gesendet werden, wenn sich der Kunde auf der Produktseite befindet.

Beispiele:

// 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 – Produkt zur Merkliste hinzugefügt

Dieses Event wird gesendet, wenn der Kunde seiner Merkliste ein Produkt hinzufügt.

Hinweis:

Parameter in eckigen Klammern [ ] sind optionale Parameter. Die Warenkorb-ID wird noch nicht in Reports angezeigt.

Beispiele:

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

// Als Event angehängt
etCommerce.attachEvent({'mousedown' : ['insertButton']}, 'insertToWatchlist', product, 2);

removeFromWatchlist – Produkt von Merkliste entfernt

Mit Hilfe dieses Events können Sie feststellen, welche Produkte wieder von der Merkliste entfernt wurden.

Hinweis:

Parameter in eckigen Klammern [ ] sind optionale Parameter.

Beispiele:

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

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

insertToBasket – Produkt in den Warenkorb gelegt

Dieses Event wird gesendet, wenn der Kunde seinem Warenkorb ein Produkt hinzufügt.

Beispiele:

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

// Als Event angehängt
etCommerce.attachEvent({'mousedown' : ['insertButton']}, 'insertToBasket', product, 2);

removeFromBasket – Produkt aus dem Warenkorb entfernt

Mit Hilfe dieses Events können Sie feststellen, welche Produkte wieder aus einem Warenkorb entfernt wurden.

Beispiele:

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

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

order – Bestellung

Dieses Event übermittelt die gesamte Bestellung mit allen Bestelldaten und dem Warenkorb.

Beispiele:

// 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 – Bestellung vom Status Lead in den Status Sale transferiert

Dieses Event wird gesendet, wenn eine Bestellung inklusive aller Produktpositionen vom Status “Lead“ in den Status “Sale“ überführt werden soll.

Beispiele:

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

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

orderCancellation – Bestellung storniert

Dieses Event wird gesendet, wenn der Kunde die gesamte Bestellung storniert.

Beispiele:

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

orderPartialCancellation – Bestellung teilstorniert

Dieses Event wird gesendet, wenn nur einzelne Produkte einer Bestellung storniert werden.

Beispiele:

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

Die Informationen zu den Produkten, den Warenkörben und den Bestellungen werden in JavaScript-Objekten abgelegt. Im Folgenden finden Sie eine Aufstellung dieser Objekte und deren Aufbau.

• Das Produkt-Objekt
  
• Das Warenkorb-Objekt
  
• Das Bestell-Objekt
  

Das Produkt-Objekt

Dieses Objekt definiert ein Produkt mit den dazugehörigen Attributen.

Beispiel:

// 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'}};

Das Warenkorb-Objekt

Bei einer Bestellung werden die bestellten Produkte in einem Warenkorb-Objekt abgelegt.

Das Array “products“ enthält ein oder mehrere Objekte, die wiederum aus Produkt-Objekten und der jeweiligen Anzahl bestehen. Dieses Produkte-Array findet auch in einer Teilstornierung Verwendung.

Beispiel:

// Definition eines Warenkorb-Objekts mit Produkte-Array
var basket = { id : '3', products : [ { product: { … }, quantity : 2 }, { product: { … }, quantity : 1 } ]};

Das Bestell-Objekt

Das Objekt der Bestellung enthält sämtliche Bestelldaten und das Warenkorb-Objekt.

Hinweis:

Parameter in eckigen Klammern [ ] sind optionale Parameter.

Beispiel:

// 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'};

Anwendungsbeispiele

Die Anwendungsbeispiele verdeutlichen, wie die verschiedenen Events für ausgewählte Aktionen auf der Website an signalize gesendet werden können.

• Produktseite angesehen
  
• Produkt in den Warenkorb gelegt
  
• Ein Produkt aus dem Warenkorb entfernen
  
• Eine Bestellung beim Klick absenden
  

Produktseite angesehen

Beim Aufrufen einer Produktseite sollen die Produktinformationen sofort übermittelt werden. Dafür wird ein Produkt-Objekt definiert. Die Daten werden über die “sendEvent“-Funktion direkt übermittelt.

Beispiel:

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

Produkt in den Warenkorb gelegt

Um Produkte zu erfassen, die in den Warenkorb gelegt werden (durch Klicken auf einen “in den Warenkorb legen“-Button), ist ein Event zu definieren, das sich an den vorhandenen Button hängt. Zuvor muss ein Produkt-Objekt definiert werden, das die Produktdaten enthält. Die ID des Buttons lautet in diesem Fall “ButtonAddToBasket“ und die Datenübermittlung erfolgt, wenn das JavaScript-Event mousedown ausgelöst wird. Die Anzahl der erfassten Produkte ergibt sich aus einem auf der Webseite hinterlegten Formularfeld “ProductQuantity“.

Beispiel:

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

Ein Produkt aus dem Warenkorb entfernen

Um die Information zu übermitteln, dass der Kunde ein Produkt wieder aus dem Warenkorb genommen hat, muss das Event “removeFromBasket“ aufgerufen werden. Die Daten werden über die “sendEvent“-Funktion direkt übermittelt.

Beispiel:

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

Eine Bestellung beim Klick absenden

Um eine Bestellung direkt beim Klicken auf den Bestellknopf anzumelden, benötigt man ein Event “order“, das an den Button “sendOrder“ angehängt wird. Die Daten werden über die “sendEvent“-Funktion direkt übermittelt.

Beispiel:

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