Enhanced ecommerce

The enhanced ecommerce plug-in for analytics.js enables the measurement of user interactions with products on ecommerce websites across the user's shopping experience, including: product impressions, product clicks, viewing product details, adding a product to a shopping cart, initiating the checkout process, transactions, and refunds.

Migration and Compatibility with Ecommerce Plug-in (ecommerce.js)

If you've already implemented Ecommerce measurement and want to start using Enhanced Ecommerce there are two main options:

Use a new property

You can add an additional tracker for a newly created property and tag/enable Enhanced Ecommerce for the new property. See Working with Multiple Tracking Objects for details on how to send data to multiple properties from a single page.

Migrate an existing property

To migrate from the ecommerce plug-in to the enhanced ecommerce plug-in, current analytics.js users should remove and replace references with enhanced ecommerce code.

If you are currently using ga.js, you will need to first migrate to analytics.js before using the enhanced ecommerce plug-in.

Transaction and item data previously collected using the ecommerce.js plug-in will not be affected by the migration and will remain available in the properties and profiles to which they were originally sent.

Enhanced Ecommerce Data Types and Actions

There are multiple types of ecommerce data you can send:

Impression Data

Represents information about a product that has been viewed. It is referred to as an impressionFieldObject and contains the following values:

Key Value Type Required Description
id text *Yes

The product ID or SKU (e.g. P67890).

* One of id or name must be set.

name text *Yes

The name of the product (e.g. Android T-Shirt).

* One of id or name must be set.

list text No The list or collection to which the product belongs (e.g. Search Results)
brand text No The brand associated with the product (e.g. Google).
category text No The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
variant text No The variant of the product (e.g. Black).
position integer No The product's position in a list or collection (e.g. 2).
price number No The price of a product (e.g. 29.20).

Product Data

Product data represents individual products that were viewed, added to the shopping cart, etc. It is referred to as a productFieldObject and contains the following values:

Key Value Type Required Description
id text *Yes

The product ID or SKU (e.g. P67890).

* One of id or name must be set.

name text *Yes

The name of the product (e.g. Android T-Shirt).

* One of id or name must be set.

brand text No The brand associated with the product (e.g. Google).
category text No The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
variant text No The variant of the product (e.g. Black).
price number No The price of a product (e.g. 29.20).
quantity integer No The quantity of a product (e.g. 2).
coupon text No The coupon code associated with a product (e.g. SUMMER_SALE13).
position integer No The product's position in a list or collection (e.g. 2).

Promotion Data

Represents information about a promotion that has been viewed. It is referred to a promoFieldObject and contains the following values:

Key Value Type Required Description
id text *Yes

The promotion ID (e.g. PROMO_1234).

* One of id or name must be set.

name text *Yes

The name of the promotion (e.g. Summer Sale).

* One of id or name must be set.

creative text No The creative associated with the promotion (e.g. summer_banner2).
position text No The position of the creative (e.g. banner_slot_1).

Action Data

Represents information about an ecommerce related action that has taken place. It is referred to as an actionFieldObject and contains the following values:

Key Value Type Required Description
id text *Yes

The transaction ID (e.g. T1234).

* Required if the action type is purchase or refund

affiliation text No The store or affiliation from which this transaction occurred (e.g. Google Store).
revenue number No

Specifies the total revenue or grand total associated with the transaction (e.g. 11.99). This value may include shipping, tax costs, or other adjustments to total revenue that you want to include as part of your revenue calculations.

tax number No The total tax associated with the transaction.
shipping number No The shipping cost associated with the transaction.
coupon text No The transaction coupon redeemed with the transaction.
list text No The list that the associated products belong to. Optional.
step integer No A number representing a step in the checkout process. Optional on `checkout` actions.
option text No Additional field for checkout and checkout_option actions that can describe option information on the checkout page, like selected payment method.

Product and Promotion Actions

Actions specify how to interpret product and promotion data that you send to Google Analytics.

Action Description
click A click on a product or product link for one or more products.
detail A view of product details.
add Adding one or more products to a shopping cart.
remove Remove one or more products from a shopping cart.
checkout Initiating the checkout process for one or more products.
checkout_option Sending the option value for a given checkout step.
purchase The sale of one or more products.
refund The refund of one or more products.
promo_click A click on an internal promotion.

Implementation

The following sections describe how to implement the enhanced ecommerce plug-in to measure ecommerce activity on a website with the analytics.js library.

Load the Ecommerce Plugin

To reduce the size of the analytics.js library, enhanced ecommerce is not provided in the default library. Instead it is provided as a plugin module that must be loaded before being used.

To load the enhanced ecommerce plugin, use the following command:

ga('require', 'ec');

This command must occur after you create your tracker object and before you use any of the enhanced ecommerce specific functionality.

Sending Enhanced Ecommerce Data

Once loaded, a couple of new commands specific to enhanced ecommerce will be added to the default tracker and you can begin sending ecommerce data.

Measuring Ecommerce Activities

A typical enhanced ecommerce implementation will measure product impressions, and any of the following actions:

  • Clicks on a product link.
  • Viewing product details.
  • Impressions and clicks of internal promotions.
  • Adding/removing a product from a shopping cart.
  • Initiating the checkout process for a product.
  • Purchases and refunds.

Measuring Impressions

Product impressions are measured using the ec:addImpression command. Details about the product are added in an impressionFieldObject.

For example, the following code measures the impression of a product in a list of search results:

ga('ec:addImpression', {            // Provide product details in an impressionFieldObject.
  'id': 'P12345',                   // Product ID (string).
  'name': 'Android Warhol T-Shirt', // Product name (string).
  'category': 'Apparel/T-Shirts',   // Product category (string).
  'brand': 'Google',                // Product brand (string).
  'variant': 'Black',               // Product variant (string).
  'list': 'Search Results',         // Product list (string).
  'position': 1,                    // Product position (number).
  'dimension1': 'Member'            // Custom dimension (string).
});

An impressionFieldObject must have a name or id value. All other values are optional and don't need to be set.

Measuring Actions

Actions are measured by using the ec:addProduct command with a productFieldObject to add product details, and the ec:setAction command to specify the action being performed.

For example, the following code measures a click on a product link displayed in a list of search results:

ga('ec:addProduct', {               // Provide product details in a productFieldObject.
  'id': 'P12345',                   // Product ID (string).
  'name': 'Android Warhol T-Shirt', // Product name (string).
  'category': 'Apparel',            // Product category (string).
  'brand': 'Google',                // Product brand (string).
  'variant': 'Black',               // Product variant (string).
  'position': 1,                    // Product position (number).
  'dimension1': 'Member'            // Custom dimension (string).
});

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

A productFieldObject must have a name or id value. All other values are optional and don't need to be set.

Combining Impressions and Actions

In cases where you have both product impressions and an action, it is possible to combine and measure this in a single hit.

The example below shows how to measure a product detail view with a related products section:

// The impression from a Related Products section.
ga('ec:addImpression', {            // Provide product details in an impressionFieldObject.
  'id': 'P12345',                   // Product ID (string).
  'name': 'Android Warhol T-Shirt', // Product name (string).
  'category': 'Apparel/T-Shirts',   // Product category (string).
  'brand': 'Google',                // Product brand (string).
  'variant': 'Black',               // Product variant (string).
  'list': 'Related Products',       // Product list (string).
  'position': 1                     // Product position (number).
});

// The product being viewed.
ga('ec:addProduct', {                 // Provide product details in an productFieldObject.
  'id': 'P67890',                     // Product ID (string).
  'name': 'YouTube Organic T-Shirt',  // Product name (string).
  'category': 'Apparel/T-Shirts',     // Product category (string).
  'brand': 'YouTube',                 // Product brand (string).
  'variant': 'gray',                  // Product variant (string).
  'position': 2                       // Product position (number).
});

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

Measuring Transactions

Measure a transaction by using the ec:setAction command and setting the action type to purchase. Transaction level details like total revenue, tax, and shipping are provided in an actionFieldObject:

ga('ec:addProduct', {               // Provide product details in an productFieldObject.
  'id': 'P12345',                   // Product ID (string).
  'name': 'Android 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).
  'coupon': 'APPARELSALE',          // Product coupon (string).
  'quantity': 1                     // Product quantity (number).
});

ga('ec:setAction', 'purchase', {          // Transaction details are provided in an actionFieldObject.
  'id': 'T12345',                         // (Required) Transaction id (string).
  'affiliation': 'Google Store - Online', // Affiliation (string).
  'revenue': '37.39',                     // Revenue (number).
  'tax': '2.85',                          // Tax (number).
  'shipping': '5.34',                     // Shipping (number).
  'coupon': 'SUMMER2013'                  // Transaction coupon (string).
});

An actionFieldObject must have an id value if the action type is purchase or refund. All other values are optional and don't need to be set.

Measuring Refunds

To refund an entire transaction, set a refund action and provide the transaction ID:

// Refund an entire transaction.
ga('ec:setAction', 'refund', {
  // Transaction ID is only required field for full refund.
  'id': 'T12345'
});

If a matching transaction is not found, the refund hit will not be processed.

To measure a partial refund, set a refund action and specify the transaction ID, product ID(s), and product quantities to be refunded:

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

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

Using Non-Interaction Events for Refunds

If you need to send refund data using an event and the event is not part of normally measured onsite behavior (i.e. not user initiated), then it’s recommended that you send a non-interaction event. This will prevent metrics such as bounce rate, time on site, etc. from being affected by the event. For example:

ga('send', 'event', 'Ecommerce', 'Refund', {'nonInteraction': 1});

Measuring the Checkout Process

To measure each step in a checkout process:

  • Add code to measure each step of the checkout process.
  • If applicable, add code to measure checkout options.
  • Optionally set user-friendly step names for the checkout funnel report by configuring Ecommerce Settings in the admin section of the web interface.

1. Measuring Checkout Steps

For each step in your checkout process, you’ll need to implement the corresponding code to send data to Google Analytics:

  • step Field

    For each checkout step that you measure you should include a step value. This value is used to map your checkout actions to the labels you configured for each step in Ecommerce Settings.

  • option Field

    If you have additional information about the given checkout step at the time the step is measured, you can set the option field with a checkout action to capture this information. For example, the default payment type for the user (e.g. Visa).

  • Measuring a Checkout Step

    To measure a checkout step, use ec:addProduct for each product, and ec:setAction indicate a checkout. If applicable, ec:setAction can take an additional actionFieldObject to describe the checkout step with a step and an option.

    The following example shows how to measure the first step of a checkout process, with a single product, and some additional information about the payment type:

    ga('ec:addProduct', {               // Provide product details in an productFieldObject.
  'id': 'P12345',                   // Product ID (string).
  'name': 'Android 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).
});

// Add the step number and additional info about the checkout to the action.
ga('ec:setAction','checkout', {
    'step': 1,
    'option': 'Visa'
});

2. Measuring Checkout Options

Checkout options allow you to measure additional information about the state of the checkout. This is useful in cases where you’ve measured a checkout step during the initial pageview but additional information about the same checkout step is available after a user selected option has been set. For example, the user selects a shipping method.

To measure a checkout option, use ec:setAction to indicate a checkout_option and include the step number, and the option description.

You’ll likely want to measure this action once the user has clicked to move on to the next step in the checkout process. For example:

// (On "Next" button click)
ga('ec:setAction', 'checkout_option', {'step': 2, 'option': 'FedEx'});

ga('send', 'event', 'Checkout', 'Option', {
    hitCallback: function() {
      // advance to next page
    },
});

3. Checkout Funnel Configuration

Each step in your checkout process can be given a descriptive name that will be used in reports. To configure these names, visit the Admin section of the Google Analytics Web Interface, select the view (profile) and click on Ecommerce Settings. Follow the Ecommerce set-up instructions to label each checkout step you intend to measure.

Ecommerce Settings in the Admin section of the Google Analytics web interface. Ecommerce is enabled and 4 checkout-funnel step labels have been added: 1. Review Cart, 2. Collect Payment Info, 3. Confirm Purchase Details, 4. Receipt
Figure 1: Ecommerce Setup - Checkout Funnel

Measuring Internal Promotions

The enhanced ecommerce plug-in includes support for measuring impressions and clicks of internal promotions, such as banners displayed to promote a sale on another section of a website.

Promotion Impressions

Internal promotion impressions are generally measured when the page loads and are sent with the initial pageview using the ec:addPromo command. For example:

ga('ec:addPromo', {               // Promo details provided in a promoFieldObject.
  'id': 'PROMO_1234',             // Promotion ID. Required (string).
  'name': 'Summer Sale',          // Promotion name (string).
  'creative': 'summer_banner2',   // Creative (string).
  'position': 'banner_slot1'      // Position  (string).
});

Promotion Clicks

Clicks on internal promotions can be measured by setting the promo_click action. For example:

// Identify the promotion that was clicked.
ga('ec:addPromo', {
  'id': 'PROMO_1234',
  'name': 'Summer Sale',
  'creative': 'summer_banner2',
  'position': 'banner_slot1'
});

// Send the promo_click action with an event.
ga('ec:setAction', 'promo_click');
ga('send', 'event', 'Internal Promotions', 'click', 'Summer Sale');

For example, to measure a product detail page with an impression and a promo click, first send product and impression data with the initial pageview, then send promo click data in a separate event:

// 1. Send product and impression data with pageview.
ga('ec:addProduct', {
  'id': 'P12345',                   // Product ID (string).
  'name': 'Android Warhol T-Shirt', // Product name (string).
  'category': 'Apparel',            // Product category (string).
  'brand': 'Google',                // Product brand (string).
  'variant': 'Black',               // Product variant (string).
  'position': 1,                    // Product position (number).
});

// The impression from the Related Products section.
ga('ec:addImpression', {
  'id': 'P12345',                   // Product ID (string).
  'name': 'Android Warhol T-Shirt', // Product name (string).
  'category': 'Apparel/T-Shirts',   // Product category (string).
  'brand': 'Google',                // Product brand (string).
  'variant': 'Black',               // Product variant (string).
  'list': 'Related Products',       // Product list (string).
  'position': 1,                    // Product position (number).
});

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

ga('send', 'pageview');             // Send the product data with initial pageview.


// 2. Send the promo click data when the promo click occurs.
// Call this function when promo click occurs.
function onPromoClick() {
  ga('ec:addPromo', {
    'id': 'PROMO_1234',
    'name': 'Summer Sale',
    'creative': 'summer_banner2',
    'position': 'banner_slot1'
  });

  // Send the promo_click action with an event.
  ga('ec:setAction', 'promo_click');
  ga('send', 'event', 'Internal Promotions', 'click', 'Summer Sale');
}

A promoFieldObject must have a name or id value. All other values are optional and don't need to be set.

Complete Example

The code snippets below show how the ecommerce lifecycle of a single product can be measured from initial impression to transaction using the enhanced ecommerce plug-in.

Measuring a Product Impression

In this example, a user first views the product in a list of search results. To measure this product impression, use the ec:addImpression command and provide the product details in an impressionFieldObject:

ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');

ga('ec:addImpression', {
  'id': 'P12345',                   // Product details are provided in an impressionFieldObject.
  'name': 'Android Warhol T-Shirt',
  'category': 'Apparel/T-Shirts',
  'brand': 'Google',
  'variant': 'black',
  'list': 'Search Results',
  'position': 1                     // 'position' indicates the product position in the list.
});

ga('ec:addImpression', {
  'id': 'P67890',
  'name': 'YouTube Organic T-Shirt',
  'category': 'Apparel/T-Shirts',
  'brand': 'YouTube',
  'variant': 'gray',
  'list': 'Search Results',
  'position': 2
});

ga('send', 'pageview');              // Send product impressions with initial pageview.

Measuring a Product Click

Next, a user expresses interest in this particular product by clicking on the product listing to view more details.

To measure that product click, use ec:addProduct and ec:setAction:

// Called when a link to a product is clicked.
function onProductClick() {
  ga('ec:addProduct', {
    'id': 'P12345',
    'name': 'Android Warhol T-Shirt',
    'category': 'Apparel',
    'brand': 'Google',
    'variant': 'black',
    'position': 1
  });
  ga('ec:setAction', 'click', {list: 'Search Results'});

  // Send click with an event, then send user to product page.
  ga('send', 'event', 'UX', 'click', 'Results', {
    hitCallback: function() {
      document.location = '/product_details?id=P12345';
    }
  });
}

The product link could then be implemented like this:

<a href="/next-page.html"
   onclick="onProductClick(); return !ga.loaded;">
  Android Warhol T-Shirt
</a>

Measuring a Product Details View

After clicking on the product listing, a user views the product details page.

To measure this product details view, use ec:addProduct and ec:setAction to specify a detail action:

ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');

ga('ec:addProduct', {
  'id': 'P12345',
  'name': 'Android Warhol T-Shirt',
  'category': 'Apparel',
  'brand': 'Google',
  'variant': 'black'
});

ga('ec:setAction', 'detail');

ga('send', 'pageview');       // Send product details view with the initial pageview.

Measuring an Addition or Removal from Cart

The user expresses intent to buy the item by adding it to a shopping cart.

To measure the addition or removal of a product from a shopping cart, use ec:addProduct and set the type add or remove:

// Called when a product is added to a shopping cart.
function addToCart(product) {
  ga('ec:addProduct', {
    'id': product.id,
    'name': product.name,
    'category': product.category,
    'brand': product.brand,
    'variant': product.variant,
    'price': product.price,
    'quantity': product.qty
  });
  ga('ec:setAction', 'add');
  ga('send', 'event', 'UX', 'click', 'add to cart');     // Send data using an event.
}

Measuring Checkout Process

Now the user is ready to begin the checkout process, which in this example includes two steps, each on separate pages:

  • Add payment details (payment.html).
  • Add shipping details (shipping.html).

If applicable, ensure you have properly configured a checkout-funnel in the Web Interface Admin, under Ecommerce Settings. For example:

Ecommerce Settings in the Admin section of the Google Analytics web interface. Ecommerce is enabled and w checkout-funnel step labels have been added: 1. Payment Details, and 2. Shipping Details
Figure 2: Ecommerce Setup - Checkout Funnel

Step 1 - Payment

To measure the first step of the checkout, use ec:addProduct for each product in the shopping cart, and ec:setAction to indicate a checkout. ec:setAction takes an actionFieldObject to describe the checkout step with a number and additional information about the default payment type for this user has been included using the option field:

ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');

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

// In the case of checkout actions, an additional actionFieldObject can
// specify a checkout step and option.
ga('ec:setAction','checkout', {
    'step': 1,            // A value of 1 indicates this action is first checkout step.
    'option': 'Visa'      // Used to specify additional info about a checkout stage, e.g. payment method.
});
ga('send', 'pageview');   // Pageview for payment.html

Step 2 - Shipping

To measure the second step of the checkout, use ec:addProduct for each product in the shopping cart, and ec:setAction to indicate a checkout. In this case we don’t have additional information about the shipping option selected when the initial pageview is sent so this will be handled separately using the ec:setAction to indicate a checkout_option.

// Measure checkout step 2:
ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');

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

ga('ec:setAction','checkout', {'step': 2});
ga('send', 'pageview');     // Pageview for shipping.html


// Called when user has completed shipping options.
function onShippingComplete(stepNumber, shippingOption) {
  ga('ec:setAction', 'checkout_option', {
    'step': stepNumber,
    'option': shippingOption
  });

  ga('send', 'event', 'Checkout', 'Option', {
     hitCallback: function() {
       // Advance to next page.
     }
  });
}

The form could then be implemented like this:

<a href="/next-page.html"
   onclick="onShippingComplete(2, 'FedEx'); return !ga.loaded;">
  Continue
</a>

Measuring a Transaction

Lastly, the user completes the checkout process and submits their purchase.

To measure the sale of one or more products, use ec:addProduct to add each product, then ec:setAction to specify a purchase. Transaction level information like total revenue, tax, etc. can be specified via an actionFieldObject. For example:

ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');

ga('ec:addProduct', {
  'id': 'P12345',
  'name': 'Android Warhol T-Shirt',
  'category': 'Apparel',
  'brand': 'Google',
  'variant': 'black',
  'price': '29.20',
  'quantity': 1
});

// Transaction level information is provided via an actionFieldObject.
ga('ec:setAction', 'purchase', {
  'id': 'T12345',
  'affiliation': 'Google Store - Online',
  'revenue': '37.39',
  'tax': '2.85',
  'shipping': '5.34',
  'coupon': 'SUMMER2013'    // User added a coupon at checkout.
});

ga('send', 'pageview');     // Send transaction data with initial pageview.

Specifying Local Currencies

By default, you can configure a common, global, currency for all transactions and items through the Google Analytics management web interface. By default, the global currency is used for all items and transactions. For websites that conduct transactions in multiple currencies, the ecommerce plugin allows you to specify the local currency of the transaction.

The local currency must be specified in the ISO 4217 standard. Read the Currency Codes Reference document for a complete list of supported conversion currencies.

Local currencies are specified using the currencyCode tracker property. For example, this tracker will send currency values as Euros:

ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');

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

ga('ec:addProduct', {
  'id': 'P12345',
  'name': 'Android Warhol T-Shirt',
  'category': 'Apparel',
  'brand': 'Google',
  'variant': 'black',
  'price': '21.89',
  'quantity': 1
});

ga('ec:setAction', 'purchase', {
  id: 'T12345',
  affiliation: 'Google Store - Online',
  revenue: '28.03',
  tax: '2.14',
  shipping: '4.00',
  coupon: 'SUMMER2013'
});

ga('send', 'pageview');