eCommerce Events

With the help of eCommerce Events, actions like “Product page seen”, “Product placed into the basket” or “Product ordered” can be transferred with all of the relevant item information. Here, however, additional code needs to be integrated. The functions and parameters for this are included in the so-called eCommerce API.

This relates to JavaScript code which needs to be integrated into the corresponding pages on your website. The eCommerce API 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. This function is to be inserted if an event is to be run when a page is opened.

If sending is to be coupled to a specific (or already existing) JavaScript event, the function attachEvent needs to be used. An example for this is clicking a button for which a layer opens. What’s important here is that each HTML element, to which an eCommerce event is to be attached, has an ID. As such, the HTML parameter “id” always needs to have a value.

Using these two functions, the following available events can be recorded:

  • viewProduct – Product seen
  • insertToBasket – Product placed into basket
  • removeFromBasket – Product removed from basket
  • order – Order
  • orderCancellation – Order cancelled

With each event, so-called objects need to be defined and entered. The objects refer to:

  • product: This object defines a product with the respective attributes. The attributes of a product object are:
    • Product ID
    • Product name
    • Product hierarchy (category, up to four category levels)
    • (Nominal) price
  • basket: With an order, the ordered products are placed into a basket object. Here, a basket ID is transferred and the products, which can be found in the basket, are recorded. With the “viewProduct” event, the basket ID must be included.
  • order: The object of the order contains all order data and the basket object. The following order data will be recorded:
    • Order number: For the clear identification of turnover targets achieved by visitors (leads and sales), a clear value will be sent to etracker so that each booking can be recorded individually.
    • Status: When ordering, this is the status “sale”.
    • Order value: Total order value.
    • Basket: The basket object (see above)
Note:
When integrating the eCommerce API, debug mode is very useful if you wish to find possible transfer errors more quickly.

  • This event should be transferred each time a product page is viewed. A product should be evaluated as “seen” if it is possible to place it into the basket from this page.
    Note: This means if products are placed directly from the category overview page into the basket, a “Product seen event” must be called at the same time as the “Product placed in basket event”.
    3-1_produkt-gesehen Defining the Product Object
    NameAttributeData typeFor company
    Product IDidstring, max. 50 charactersA real or fictitious, but simultaneously unique product number
    Product namenamestring, max. 250 charactersA real or fictitious, but simultaneously real product name
    Product categorycategoryarray of strings, max. 50 characters/stringCategory level 1-4
    (Normal) pricepricestring, max. 20 charactersA real or fictitious monetary value for the product
    Note: The product object requires two additional attributes when transferring to the eCommerce- API: “currency” and “variants”. An individual adjustment to this attribute is currently not possible.
    When transferring the “viewProduct” event, the function “sendEvent” must be used on a product page. Accordingly, the following example code is needed to trigger the event: Product: Product A Item number: 125125125 Item name: Product A Price: 25.99 Category level 1: Upper category X Category level 2: Lower category X.Y. Category level 3: Lower category X.Y.Z Category level 4: Special category i
    var et_Commerce_product = 
     {
      id : '125125125', 
      name : 'Product A', 
      category : [‘Upper category X’, 'Lower category X.Y.', 'Lower category X.Y.Z.', 'Special category i'], 
      price : '25.99',
      currency: 'EUR',
      variants: {}
    };
    etCommerce.sendEvent('viewProduct',et_Commerce_product)
    This event is triggered when the user clicks the “into the basket” button. When transferring with a click, you must use the “attachEvent” function. 3-2_produkt-in-den-warenkorb-gelegt Accordingly, the following example code is needed to trigger the event:
    var et_Commerce_product = {  id : '125125125',   name : 'Product A',   category : [‘UpperCategory X’, 'LowerCategory X.Y.', 'LowerCategory X.Y.Z.', 'SpecialCategory i'],   price : '25.99',   currency: 'EUR',  variants: {}}; var quantity = '1';etCommerce.attachEvent({'mousedown' : ['ButtonOffer']}, 'insertToBasket',et_Commerce_product,quantity);
    This event is triggered when the confirmation page of a purchase displays. Here, an order object needs to be defined. Definition of an order object
    NameAttributeData typeDescription
    Order numberorderNumberstring, max. 50 charactersID of purchase or order number. If this is no longer available, a different unique value from the CMS or, if necessary, a continuous number, can be transferred.
    StatusstatusenumSale
    Order valueorderPricestringThe total volume decimal separator is a dot.
    CurrencycurrencystringCurrency of the order according to ISO 4217: EUR, GBP or USD
    Shopping basketbasketobject of warenkorbThe basket object - see above
    The following example refers to the following content: Product: Product A Item number: 125125125 Item name: Product A Price: 25.99 Category level 1: Upper category X Category level 2: Lower category X.Y. Category level 3: Lower category X.Y.Z Category level 4: Special category i Accordingly, the following example code is needed to trigger the event:
    var orderObject = {    orderNumber : 'ABC12345',    status : 'sale',      orderPrice : '25.99',    basket : {        id : '1',        products : [            {                product: {  id : '125125125',   name : 'Product A',   category : [‘UpperCategory X’, 'LowerCategory X.Y.', 'LowerCategory X.Y.Z.', 'SpecialCategory i'],   price : '25.99',   currency: 'EUR',  variants: {}                       },                quantity : 1            }                ]    },}etCommerce.sendEvent('order', orderObject);
    The following is an example in which the potential customer orders multiple products in a single selection: Product: Product A Product ID: 123456789 Product name: Product A Category level 1: Category X Category level 2: Category X.Y. Category level 3: Category X.Y.Z. Category level 4: Brand i Price: 129,56 Quantity: 3 Product: Product B Product ID: 234567890 Product name: Product B Category level 1: Category A Category level 2: Category B Category level 3: Category C Category level 4: Brand ii Price: 23,99 Quantity: 1 Accordingly, the following example code is needed to trigger the event:
    var orderObject = {    orderNumber: 'ABC12345',    status: 'Sale',    orderPrice: '412.67',    currency: 'EUR',    basket: {        id: '1',        products: [{            product: {                id: '123456789',                name: 'Product A',                category: ['Category X', 'Category X.Y.', 'Category X.Y.Z.', 'Brand i'],                price: '129.56',                currency: 'EUR',                variants: {}           },            quantity = '3'        }, {            product: {                id: '234567890',                name: 'Produkt B',                category: ['Category A', 'Category B', 'Category C', 'Brand ii'],                price: '23.99',                currency: 'EUR',                variants: {}            },            quantity = '1'        }]    },}
    etCommerce.sendEvent('order',orderObject);
    It is also possible to record the shipping costs as a product in itself. To do so we have the following example: Product: Product A Product ID: 23456789 Product name: Product A Category level 1: Category X Category level 2: Category X.Y. Category level 3: Category X.Y.Z. Category level 4: Brand i Price: 129,56 Quantity: 3 Product: Product B Product ID: 234567890 Product name: Product B Category level 1: Category A Category level 2: Category B Category level 3: Category C Category level 4: Brand ii Price: 23,99 Quantity: 1 Produkt: Versandkosten Produkt-ID: Shipping costs Produkt-Name: Shipping costs Category level 1: Shipping costs Category level 2: Category level 3: Category level 4: Price: 4,99 Quantity: 1 Accordingly, the following example code is needed to trigger the event:
    var orderObject = {    orderNumber: '123456789',    status: 'Sale',    orderPrice: '417.66',    currency: 'EUR',    basket: {        id: '1',        products: [{            product: {                id: '123456789',                name: 'Product A',                category: ['Category X', 'Category X.Y.', 'Category X.Y.Z.', 'Brand i'],                price: '129.56',                currency: 'EUR',                variants: {}            },            quantity = '3'        }, {            product: {                id: '123456789',                name: 'Product B',                category: ['Category A', 'Category B', 'Category C', 'Brand ii'],                price: '23.99',                currency: 'EUR',                variants: {}            },            quantity = '1'        }, {            product: {                id: 'Shipping costs',                name: 'Shipping costs',                category: ['Shipping costs', '', '', ''],                price: '4.99',                currency: 'EUR',                variants: {}            },            quantity = '1'        }]    },}
    etCommerce.sendEvent('order', orderObject);

Need help?
Our friendly, knowledgeable support engineers are here for you.