Skip to content
Enhanced Ecommerce

How to Implement Enhanced eCommerce on your website

This document describes the enhanced eCommerce features available via analytics.js

Overview

Analytics.js enhanced eCommerce functions allow to monitor the way users interact with your online store, and its products, and to optimize their experience during the various steps of the checkout process.

The following data are monitored:

  • Product impressions.
  • Product clicks.
  • Products detailed.
  • Adding a product to a shopping cart.
  • Removing a product from a shopping cart.
  • Transactions, and refunds.
  • Various steps of the checkout process.

Compatibility with basic eCommerce functions

Enhanced eCommerce functions should not be used together with basic eCommerce functions. The two systems must not coexist.

If you've already implemented basic eCommerce functions and want to start using enhanced eCommerce commands, you should remove all code using the basic eCommerce functions from your website.

Enhanced eCommerce data types and actions

Several types of data are used by analytics.js :

  • Impression data,
  • Product data,
  • Action data,
  • Action types.

Impression data

Impression data is increased whenever a product is displayed on any page of your online store.

Impression data accepted properties are :

Key Type Required Description
id text Yes The product ID or SKU (e.g.P67890).
name text Yes Label of the product (e.g. battle pants).
list text No The list to which the product belongs (e.g. Search Results)
brand text No The product brand (e.g. : Lewis).
category text No The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify the level of hierarchy (e.g. Apparel/Men/Pants).
variant text No The variant of the product (e.g. Black).
position integer No Product position in a list. (e.g. 2)
price number No The product price (e.g. 29.20).
currency devise No Devise ISO 4217.

Product Data

This is the data describing an individual product. These data are used when a product is viewed in detail, added or removed from the shopping cart, purchased, etc.

Product data accepted properties are :

Key Type Required Description
id text Yes The product ID or SKU (e.g.P67890).
name text Yes Name of the product (e.g. battle pants).
brand text No The product brand (e.g. : Lewis).
category text No The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify the level of hierarchy (e.g. Apparel/Men/Pants).
variant text No The variant of the product (e.g. Black).
price number No The price of the product excluding taxes. (e.g. 29.20)
quantity integer No The quantity (e.g. 2).
coupon text No The coupon code associated with a product (e.g. SAVE10).
position integer No Product position in a list. (e.g. 2).
currency devise No Devise ISO 4217.

Action Data

These are the data attached to an action.

Action data accepted properties are:

Key Type Required Description
id text Yes The transaction ID. Required for « purchase » or « refund » action type.
affiliation text No The store or affiliation from which this transaction occurred.
revenue number No Specifies the total amount including taxes of the transaction.
shipping number No The shipping cost associated with the transaction. including taxes
tax number No taxes including taxes on shipping.
currency devise No Devise ISO 4217 (wikipedia.org/wiki/ISO_4217)
coupon text No The coupon attached to the transaction
list text No The list that the associated products belong to.
step integer No A number representing a step in the checkout process. Used with the action type "checkout".
option text No Additional field for "checkout" and "checkout_option" actions.
revenue_tax number No Taxes on the amount of the transaction
shipping_tax number No Taxes on the amount of the shipping
revenue_net number No Amount of the transaction exluding taxes
shipping_net number No Amount of the shipping excluding taxes

Type of Actions

An action specifies the command to be executed with the data being sent.

Action Description
click A click on a product.
detail A view of a product details.
add Adding a product (or more) to a shopping cart
remove Remove product(s) from a shopping cart
checkout Initiating the checkout process for one or more products
checkout_option Setting an option of a checkout step
purchase The sale of one or more products
refund The refund of one or more products

Enhanced eCommerce implementation

The following sections describe how to implement enhanced eCommerce on a website with analytics.js.

Sending enhanced eCommerce data

Enhanced eCommerce specific commands and data are implemented into analytics.js. It is recommended to send them after having sent the data related to the page.

Measuring enhanced eCommerce activities

The following metrics are available through enhanced eCommerce:

  • Measuring product impressions.
  • Measuring actions.
  • Combining impressions and actions.
  • Measuring Transactions.
  • Measuring Refunds.
  • Measuring the Checkout Process.

Measuring product impressions

Product impressions are measured using the "ec: addImpression" command. Data related to the product is sent via a javascript object. This object must contain the properties "name" and "id". Other properties ​​are optional.

aa('ec:addImpression', {                 // Detail about a product impression.
  'id': 'P12345',                        // Product ID (string).
  'name': 'Android Smartphone',          // Product name (string)).
  'category': 'High-tech/smartphones',   // Product category (string).
  'brand': 'Samsung',                    // Product brand (string).
  'variant': 'Black',                    // Product variant (string).
  'list': 'Search Results',              // Product list (string).
  'position': 1,                         // Product position in the list (integer).
 });

Measuring actions

First, you need to specify the product details with the "ec: addProduct" command. Then the action to be executed with the "ec: setAction" command.

aa('ec:addProduct', {                   // Add product detail.
  'id': 'P12345',                       // Product ID (string).
  'name': 'Android Smartphone',         // Product name (string).
  'category': 'High-tech/smartphones',  // Product category (string).
  'brand': 'Samsung',                   // Product brand (string).
  'variant': 'Black',                   // Product variant (string).
  'position': 1,                        // Product position in the list (number).

});

aa('ec:setAction', 'click', {       // click action.
  'list': 'Search Results'          // Product list (string).
});

Combining impressions and actions

If you need to send both product impression and action, you can combine them.

// Product details in an impression from the list "related products"
aa('ec:addImpression', {                // Product impression.
  'id': 'P12345',                       // Product ID (string).
  'name': 'Android Smartphone',         // Product name (string).
  'category': 'High-tech/smartphones',  // Product category (string).
  'brand': 'Samsung',                   // Product brand (string)
  'variant': 'Black',                   // Product variant (string).
  'list': 'produits semblables',        // Product list (string).
  'position': 1                         // Product position in the list (number).
});

// The product being viewed.
aa('ec:addProduct', {                 // Add product details.
  'id': 'P67890',                     // Product ID.
  'name': 'Organic T-Shirt',          // Product Name.
  'category': 'Apparel/T-Shirts',     // Catégory.
  'brand': 'Levis',                   // Brand.
  'variant': 'gray',                  // Variant.
  'position': 2                       // List position.
});
aa('ec:setAction', 'detail');         // Detail action.

Defining multiple products

If multiple products have been defined, the specified action will apply to all products.

// First product 
aa('ec:addProduct', {                 // Add product details.
  'id': 'P67890',                     // Product ID (string).
  'name': 'AFS T-Shirt',              // Product name (string).
  'category': 'Apparel/T-Shirts',     // Product category (string).
  'brand': 'AFS',                     // Product brand (string).
  'variant': 'gray',                  // Product variant (string).
  'price': '22'                       // Product price.
});

// Second product 
aa('ec:addProduct', {                
  'id': 'P47891',                    
  'name': 'AFS Hat',  
  'category': 'Apparel/Hat/',     
  'brand': 'AFS',
  'variant': 'black',             
  'price': ’48.50’                
});

// the third product
aa('ec:addProduct', {                
  'id': 'P47892',                    
  'name': 'Datasense T-Shirt',  
  'category': 'Apparel/T-Shirts',  
  'brand': 'Datasense',            
  'variant': 'white',              
  'price': '18.50'
});

aa('ec:setAction', 'detail');       // Detail action.

Combining multiple actions

Once the action command has been executed, the products list is emptied. However, a clear option is available which allows to combine multiple actions without redefining the products details each time.

By setting the clear option to no, you can prevent the products list deletion after the command execution.

// add product detail 
aa('ec:addProduct', {                 
  'id': 'P47892',                    
  'name': 'Datasense T-Shirt',  
  'category': 'Apparel/T-Shirts',  
  'brand': 'Datasense',            
  'variant': 'white',              
  'price': '18.50'  
});

aa("ec:SetOption", { "clear": "no"}); // Don't reset the list after the action
aa('ec:setAction', 'detail');         // Product viewed 
aa('ec:setAction', 'add');           //  Produit added to shopping cart.

Measuring Transactions

The purchase action defines a sale transaction. The third parameter is an object containing the transaction data and must include an id property. All other properties ​​are optional.

aa('ec:addProduct', {                   // Add product details
  'id': 'P860605',                      // Product ID (string).
  'name': 'iPhone 11',                  // Product Name (string).
  'category': 'High-tech/smartphones',  // Product Category (string).
  'brand': 'Google',                    // Brand (string).
  'variant': 'black',                   // Variant (string).
  'price': '29.20',                     // Product price (number).
  'coupon': 'APPARELSALE',              // Coupon attached to product (string).
  'quantity': 1                         // Quantity (number). 
});

aa('ec:setAction', 'purchase', {          // Action purchase.
  'id': 'T12345',                         // Transaction ID *Required (string)
  'affiliation': 'My Store',              // Affiliation (string).
  'revenue': '37.39',                     // Revenue with taxes (number).
  'tax': '2.85',                          // taxes (number).
  'shipping': '5.34',                     // Shipping (number).
  'coupon': 'SUMMER2013'                  // coupon used with transaction (string).
});

Measuring Refunds

For a full transaction refund, a refund action have to be sent with the related transaction ID. If this transaction does not exist, the refund will be ignored.

// Refund a full transaction.
aa('ec:setAction', 'refund', {
  'id': 'T12345'    // Transaction ID is required for a full refund.
});

To specify a partial refund, a refund action have to be be sent with the transaction ID, the product ID, and the quantity to be refunded.

// refund a single product
aa('ec:addProduct', {
  'id': 'P12345',       //  Product ID is required for partial refund.
  'quantity': 1         //  Quantity is required. 
});

ga('ec:setAction', 'refund', {
  'id': 'T12345',       // Transaction ID is required.
});

Measuring the Checkout Process

In order to monitor each step of a checkout process, you will have to:

  1. Add code specific to each step.
  2. If necessary, add code to define options.
  3. Define labels for each step in the sales funnel settings on AFS Analytics.

Measuring steps

For each funnel step you need to implement specific code to send data to AFS Analytics.

Field Description
step Defines the step number. Each time the visitor progresses through the checkout process, you must specify a step value. This value represents the step number entered in the sales funnel settings.
option Use this field whenever you need to specify additional information about a step. For example, for the "payment information" step, you can use this field to mention a payment method.

Measuring a step

Use ec: addProduct to detail each product then ec: setAction as the command action, followed by the field step containing the step value, and, if necessary, the field option .

The following example shows how to send data to analytics.js when a payment method has been selected.

The checkout process is as follows:

  1. Product(s) added to the shopping cart.
  2. Shopping cart validation by the customer.
  3. Payment information.
  4. Shipping method selection.
  5. Order Confirmation and payment.
aa('ec:addProduct', {               // Product details.
  'id': 'P12345',                   // Product ID (string).
  'name': 'Warhol T-Shirt',         // Product name (string).
  'category': 'Apparel',            // Product category (string).
  'brand': 'Google',                // Product brand (string).
  'variant': 'black',               // Product variant (string).
  'price': '29.20',                 // Product price (number).
  'quantity': 1                     // Product quantity (number).
});

// Define the step value and the related option.
aa('ec:setAction','checkout', {
    'step': 3,
    'option': 'Visa'
});

The "checkout_option" action

The checkout_option action allows you to add additional information about a step previously sent ( in the case that information was not available at the time the "checkout" action was being sent ).

//the checkout action was sent without specifying the payment method 
aa('ec:setAction', 'checkout_option', {'step': 3, 'option': 'PAYPAL'});

Sales Funnel Configuration

Each step in the funnel can be given a descriptive name that will be used in reports. To configure these names, select, on the AFS Analytics dashboard page, the option "eCommerce enhanced -> sales funnel settings" in the left menu.

Enhanced eCommerce specific options

currencyCode

This option defines the currency used by default.

aa("ec:SetOption", { "currencyCode": "USD"});

Note

You can also set the account currency with the standard option.

aa('set', 'currencyCode', 'EUR'); // Set default currency to Euros.

clear

This option allows you to define whether the list of products added with "addProduct" command should be reset after executing the action. By default this option is set to "yes".

aa("ec:SetOption", { "clear": "no"}); //the product list is not reset 
aa("ec:SetOption", { "clear": "yes"}); //the product list is reset

beacon

The Beacon option allows you to force the sending of the "action" command via the Beacon API. This option is necessary if the "action" command is sent when the page is unloaded. 

aa("ec:SetOption", { "beacon": "enabled"}); //is sent with api beacon
aa("ec:SetOption", { "beacon": "disabled"}); //is sent with XMLHttpRequest

Complete Example

The code snippets below show the different measurement available via the enhanced eCommerce functions.

Measuring product impression

A visitor first views the product in a list of search results. 

aa("create", "xxxxxxxx", "auto")  //xxxxxxxx is your website id.

aa('ec:addImpression', {
  'id': 'P12345',                   
  'name': "NoteBook",
  'category': 'higt-tech/notebook/',
  'brand': 'IBM',
  'variant': 'black',
  'list': 'Search Results',
  'position': 1                    
});

aa('send', 'pageview');

Measuring a click on a product

Then, the potential buyer clicks on the product to navigate to its page.

// Called when a link to a product is clicked.
function onProductClick() {
  aa('ec:addProduct', {
  'id': 'P12345',
  'name': "NoteBook",
  'category': 'higt-tech/notebook/',
  'brand': 'IBM',
  'variant': 'black',
  'position': 1,
  "price": "399"
  });
  aa("ec:SetOption", { "beacon": "enabled"}); //for more safety
  aa('ec:setAction', 'click', {list: 'Search Results'});
}

On the product dedicated page:

aa("create", "xxxxxxxx", "auto")  //xxxxxxxx is your website id.
aa('send', 'pageview');          
aa('ec:addProduct', {
  'id': 'P12345',
  'name': "NoteBook",
  'category': 'higt-tech/notebook/',
  'brand': 'IBM',
  'variant': 'black',
  "price": "399"
  });
  aa('ec:setAction', 'detail');

Click on the button "Add to shopping cart" on the product dedicated page

// Called when the visitor clicks on "Add to cart". product is an object with the product details.
function addToCart(product) {
  aa('ec:addProduct', {
    'id': product.id,
    'name': product.name,
    'category': product.category,
    'brand': product.brand,
    'variant': product.variant,
    'price': product.price,
    'quantity': product.qty
  });
  aa("ec:SetOption", { "beacon": "enabled"}); //only if the click unload the current page and load a new.
  aa("ec:SetOption", { "clear": "no"});  //We sent 2 actions, so we request to not clear the product details.
  aa('ec:setAction', 'add'); //Add to the shoping cart
  aa("ec:SetOption", { "clear": "yes"}); //Set clear to yes, so the list will be reset after the next action (here "checkout").
  aa('ec:setAction','checkout', {'step': 1}); //this is the first step of the sales funnel.
  // only if autotrack is set to OFF
  aa("send", "event", "click", "inside", "Add To Cart" + product.name);
}

The "Add in shopping cart" button HTML code.

<button onclick='addToCart({id:"P12345", name: "NoteBook",category:"higt-tech/notebook/",brand:"IBM",variant: "black",price:"399", quantity:1})' data-aa-label="Ajout de NoteBook dans le panier">Add in shopping cart</button>

Shopping cart validation (cart.html)

/**
 * 
This function is called when the user has validated his shopping cart.
 * @param {Array} cart An array representing the user's shopping cart.
 */

function checkout(cart) 
{
  //beacon required if the user leaves the page 
  aa("ec:SetOption", { "beacon": "enabled"});

  //get shopping cart inventory.
  for(var i = 0; i < cart.length; i++) {
    var product = cart[i];
    aa('ec:addProduct', {
      'id': product.id,
      'name': product.name,
      'category': product.category,
      'brand': product.brand,
      'variant':  product.variant,
      'price': product.price,
      'quantity': product.qty
    });
  }

  aa('ec:setAction','checkout', {
    'step': '2'            // The values 2 indicates the checkout step .
    });

}

aa("create", "xxxxxxxx", "auto")  //xxxxxxxx is your website id.
aa('send', 'pageview');

Payment page (payment.html)

/**
  * called when the user validates the payment
  * @param {Array} cart An array representing the user's shopping cart.
 */
function checkout(cart,option,step) {
  for(var i = 0; i < cart.length; i++) {
    var product = cart[i];
    aa('ec:addProduct', {
      'id': product.id,
      'name': product.name,
      'category': product.category,
      'brand': product.brand,
      'variant':  product.variant,
      'price': product.price,
      'quantity': product.qty
    });
  }

  aa("ec:SetOption", { "beacon": "enabled"}); //a new page should be loaded.
  aa('ec:setAction','checkout', {
    'step': step,            //Checkout step 3 (payement page)
    'option': option        //Payment method detail
    });

}

aa("create", "xxxxxxxx", "auto")  //xxxxxxxx is your website id.
aa('send', 'pageview');     

//call the function when the form is validated.
checkout(cart,"visa",3);

Shipping details (shipping.html)

/**
  * called when the buyer validates the shipping method
  * @param {Array} cart An array representing the user's shopping cart.
 */
function checkout(cart,option,step) {
  for(var i = 0; i < cart.length; i++) {
    var product = cart[i];
    aa('ec:addProduct', {
      'id': product.id,
      'name': product.name,
      'category': product.category,
      'brand': product.brand,
      'variant':  product.variant,
      'price': product.price,
      'quantity': product.qty
    });
  }

  aa("ec:SetOption", { "beacon": "enabled"}); //a new page will be loaded.
  aa('ec:setAction','checkout', {
    'step': step,            // Checkout step 4, the shipping page
    'option': option      // shipping method.
    });


}

aa("create", "xxxxxxxx", "auto")  //xxxxxxxx is your website id.
aa('send', 'pageview');     

//call the function when the form is validated
checkout(cart,"fedex",4);

Order accepted and paid, thank you page (thanks.html)

 for(var i = 0; i < cart.length; i++) {
    var product = cart[i];
    aa('ec:addProduct', {
      'id': product.id,
      'name': product.name,
      'category': product.category,
      'brand': product.brand,
      'variant':  product.variant,
      'price': product.price,
      'quantity': product.qty
    });
 }

  aa("create", "xxxxxxxx", "auto")  //xxxxxxxx is your website id.
  aa('send', 'pageview');     

  //do not clear the product list after executing the purchase command
  aa("ec:SetOption", { "clear": "no"}); 
  //Envoi de la transaction
  aa('ec:setAction', 'purchase', {
  'id': 'T12345',
  'affiliation': 'My Online Store',
  'revenue': '318.25',
  'tax': '68.50',
  'shipping': '15.34',
  'coupon': 'SUMMER2020'    // User added a coupon at checkout.
  });

  // Last step of the checkout: successful sale
  aa('ec:setAction','checkout', {
    'step': 5,            // Step 5 successful sale
    });
Last updated on November 23, 2020 19:23:04