- Orders and eCommerce Events
- Functionality of the eCommerce API
- How to get the eCommerce API
- Debug Mode
- Functions of the eCommerce API
- Possible Events
- Event Objects
- Examples of Use
Orders and eCommerce Events
With the help of eCommerce Events, actions like “Product page seen”, “Product placed into the basket” or “Product ordered” can be tracked. That´s done by the so-called eCommerce API.
Functionality of the eCommerce API
The eCommerce API is a JavaScript interface. It can receive different events 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 when the tracking code has loaded. The examples lower down explain the different ways to integrate 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
- Switching on Debug Mode with Configuration Object _etr
- Switching on Debug Mode with variable etCommerce.debugMode
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.
| Browser | Developer Tool | Where to find? |
|---|---|---|
| Firefox | Firebug | https://addons.mozilla.org/de/firefox/addon/firebug |
| Internet Explorer | Developer tools | Is integrated in the browser |
| Chrome | Developer tools | Is integrated in the browser |
| Opera | Dragonfly | Is integrated in the browser |
| Safari | Firebug lite | http://getfirebug.com/firebuglite |
Switching on Debug Mode with Configuration Object _etr
Note:
The configuration object can only be integrated when you use the current signalize code 4.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.
Example:
< script type="text/javascript" charset="UTF-8">
// Parameterblock
var et_pagename = "__INDEX__"; _etr = { debugMode = true; }
< script id="_etLoader" type="text/javascript" charset="UTF-8" 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
Note:
The variable etCommerce.debugMode must be set after calling the signalize code. signalize Code 4.x is called by the file e.js.
// switch to debug mode
etCommerce.debugMode = true ;
Example of signalize code 4.x etCommerce.debugMode after parameter block and signalize code:
< script type="text/javascript" charset="UTF-8">
// Parameterblock
var et_pagename = "pagename";
< /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 ;
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.
| Function parameters | Data typ | Limitation | Description |
|---|---|---|---|
| Event | string | Only those events defined by the interface are supported. | Name oft he event. |
| parameter_1, [parameter_n] | varying | See 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 Signalize.
| Function parameters | Data type | Limitation | Description |
|---|---|---|---|
| attachObject | Object | Only 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. |
| Event | string | Only those events defined by the interface are supported (see "Possible Events"). | Name of the attached event. |
| parameter_1, [parameter_n] | varying | See further description. |
Note:
Note: Parameters in square brackets [ ] are optional parameters.
Example:
// Associate the eCommerce Events with a JavaScript-Event
etCommerce.attachEvent({'mousedown' : ['viewButton']}, 'viewProduct', product, 'basket 1') ;
Possible Events
At the moment, different events are supported by the eCommerce API, which are described below.
- viewProduct – Product viewed
- insertToWatchlist – Product added to the watchlist
- removeFromWatchlist – Product removed from watchlist
- insertToBasket – Product placed into basket
- removeFromBasket – Product removed from basket
- order – Order
- orderConfirmation – Order transferred from Status Lead to Status Sale
- orderCancellation – Order cancelled
- orderPartialCancellation – Order partially cancelled
viewProduct – Product viewed
This event can be sent when a customer is on the product page.
| Function parameters | Data typ | Limitation | Description |
|---|---|---|---|
| 'viewProduct' | string | Only this name is approved. | Name oft he event. |
| Product objekt | object | The object must correspond to the product object description (see "The Product Object"). | A product object. |
Examples:
// Definition of a product objekt
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, 'basket 1') ;
insertToWatchlist – Product added to the watchlist
This event is sent when the customer adds a product to their watchlist.
| Function parameters | Data Typ | Limitation | Description |
|---|---|---|---|
| 'insertToWatchlist' | string | Only this name is approved. | Name of the event. |
| Product object | object | The object must correspond to the product object description (see "The Product Object"). | A product object. |
| Number | integer | 0 - 65 535 Negative numbers are not allowed. | The number of products placed on the watchlist. |
| [Pagename] | string | Maximum 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 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.
| Function parameters | Data typ | Limitation | Description |
|---|---|---|---|
| 'removeFromWatchlist' | string | Only this name is approved. | Name oft he event. |
| Product object | object | The object must correspond to the product object description (see "The Product Object"). | A product object. |
| Number | integer | 0 - 65 535 Negative numbers are not allowed. | The number of removed products. |
| [Seitenname] | string | Maximum 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.
Example:
// Direct call
etCommerce.sendEvent('removeFromWatchlist', product, 1) ;
// Attached as event
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.
| Function parameters | Data typ | Limitation | Description |
|---|---|---|---|
| 'insertToBasket' | string | Only this name ist approved. | Name oft he event. |
| Product object | object | The object must correspond to the product object description (see "The Product Object"). | A product object. |
| Number | integer | 0 - 65 535 Negative numbers are not allowed. | The number of products placed into the 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.
| Function parameters | Data typ | Limitation | Description |
|---|---|---|---|
| 'removeFromBasket' | string | Only this name ist approved. | Name oft he event. |
| Product object | object | The object must correspond to the product object description (see "The Product Object"). | A product object. |
| Number | integer | 0 - 65 535 Negative numbers are not allowed. | The number of products removed from the basket. |
Examples:
// Direct call
etCommerce.sendEvent('removeFromBasket', product, 1) ;
// Attached as event
etCommerce.attachEvent({'mousedown' : ['removeButton']}, 'removeFromBasket', product, 1) ;
order – Order
This event transfers the entire order with all order data as well as the basket.
| Function parameters | Data typ | Limitation | Description |
|---|---|---|---|
| 'order' | string | Only this name is allowed. | Name oft he event. |
| Order object | object | The object must correspond to the product object description (see "The Order Object"). | An order object. |
| currency | string | Maximum 3 characters long, spaces at the start and end are removed. | Currency according to ISO 4217 e.g.: EUR or USD. |
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 : 'BigTransport', paymentConditions : 'ImmediatePayment',};
// 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”.
| Function parameters | Data typ | Limitation | Description |
|---|---|---|---|
| 'orderConfirmation' | string | Only this name is approved. | Name oft he event. |
| Order number | string | Maximum 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”. |
Beispiele:
// Direct call
etCommerce.sendEvent(‘orderConfirmation’, ‘Bestellnummer 1’);
// Attached as event
etCommerce.attachEvent({‘mousedown’ :[‘cancelButton’]}, ‘orderConfirmation’, ‘OrderNumber1’) ;
orderCancellation – Order cancelled
This event is sent when the customer cancels the entire order.
| Function parameters | Data type | Limitation | Description |
|---|---|---|---|
| 'oderCancellation' | string | Only this name is approved. | Name of the event. |
| Order number | string | Maximum 50 characters long, spaces at the start and end are removed. | The order number of the order which should be cancelled. |
Examples:
// Direct call
etCommerce.sendEvent('orderCancellation', 'OrderNumber 1') ;
// Attached as event
etCommerce.attachEvent({'mousedown' : ['cancelButton']},
orderPartialCancellation – Order partially cancelled
This event is sent when only individual products of an order are sent.
| Function parameters | Data type | Limitation | Description |
|---|---|---|---|
| 'orderPartialCancellation' | string | Only this name is allowed. | Name of the event. |
| Order number | string | Maximum 50 characters long, spaces at the start and end are removed. | The order number of the order which should be cancelled. |
| Product Objects | array of objects | The 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 a product object
var products = [ { product : { id : '3445', name : 'Elfrida', category : ['Animals', 'Big', 'Giraffes', 'Love Giraffes'], price : '1723.60', }, quantity: 1}];
// Direct call
etCommerce.sendEvent('orderPartialCancellation', 'OrderNumber 1' , products) ;
// Attached as event
etCommerce.attachEvent({'mousedown' : ['partialButton']}, 'orderPartialCancellation', 'OrderNumber 1' , products) ;
Event Objects
The product 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.
| Name | Attribute | Data type | Limitation | Comment |
|---|---|---|---|---|
| Product ID | id | string | Maximum 50 characters long, spaces at the start and end are removed. | The product ID is set by you and can be derived from your inventory management system. |
| Product name | name | string | Maximum 255 characters long, spaces at the start and end are removed. | The name of the product. |
| Product hierarchy (category) | category | array of strings | Four 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) price | price | string | Maximal 20 characters long, decimal separator is a dot. Spaces at the start and end are removed. | The price of the product. |
| Currency | currency | string | Maximum 3 characters long, spaces at the start and end are removed. | Currency according to ISO 4217 e.g.: EUR or USD. |
| Variants | variants | Object 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’} . |
Example:
// 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.
| Name | Attribute | Data type | Limitation | Comment |
|---|---|---|---|---|
| Basket ID | id | string | Maximum 50 characters long, spaces at the start and end are removed. | You set the basket ID. |
| Product Objects | products | array of objects | The 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.
| Name | Attribute | Data type | Limitation | Comment |
|---|---|---|---|---|
| Product | product | object | The object must correspond to the product object description. | The Product Object. |
| Number | quantity | integer | 0 - 65 535 Negative numbers are not allowed. | The ordered/cancelled amount. |
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.
| Name | Attribute | Data type | Limitation | Comment |
|---|---|---|---|---|
| Order number | orderNumber | string | Maximum 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. |
| Status | status | enum | Contains lead, sale, cancellation or partial_cancellation. | |
| Order value | orderPrice | string | Maximum 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. |
| Currency | currency | string | Maximum 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 basket | basket | object of warenkorb | The object must correspond to the basket object description. | The Basket Object. |
| [Customer Group] | customerGroup | string | Maximum 50 characters long, spaces at the start and end are removed. | e.g. - new customer - existing customer - big buyer - VIP |
| [Delivery Conditions] | deliveryConditions | string | Maximum 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] | paymentConditions | paymentConditions | Maximum 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-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 signalize from the website.
- Product page viewed
- Product placed into basket
- Removing a Product from the Basket
- Sending an order with a click
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', };
// 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 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 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 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 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);