This guide describes how to collect enhanced ecommerce data using analytics.js.
Overview
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 tracking and want to start using Enhanced Ecommerce tracking 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 using analytics.js: impression data, product data, promotion data, and action data.
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). *Either this field or name must be set. |
name |
text | Yes* | The name of the product (e.g. Android T-Shirt). *Either this field or id 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 |
currency | 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). *Either this field or name must be set. |
name |
text | Yes* | The name of the product (e.g. Android T-Shirt). *Either this field or id 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 |
currency | 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). *Either this field or name must be set. |
name |
text | Yes* | The name of the promotion (e.g. Summer Sale). *Either this field or id 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 |
currency | 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. Note: if revenue is not set, its value will be automatically calculated using the product quantity and price fields of all products in the same hit. |
tax |
currency | No | The total tax associated with the transaction. |
shipping |
currency | 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 tracking 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 tracking will be added to the default tracker and you can begin sending ecommerce data.
- Measuring Ecommerce Activities
- Measuring Transactions
- Measuring Refunds
- Measuring the Checkout Process
- Measuring Internal Promotions
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 (currency). '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 (currency). 'tax': '2.85', // Tax (currency). 'shipping': '5.34', // Shipping (currency). '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', { 'id': 'T12345' // Transaction ID is only required field for full refund. });
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 tracking code to measure each step of the checkout process.
- If applicable, add tracking 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 tracking 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 (currency). '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 track.
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:
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 tracker 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');