Ecommerce Measurement

This guide describes how to collect ecommerce data using analytics.js.

Overview

Ecommerce measurement allows you to measure the number of transactions and revenue that your website generates. On a typical ecommerce site, once a user clicks the "purchase" button in the browser, the user's purchase information is sent to the web server, which carries out the transaction. If successful, the server redirects the user to a "Thank You" or receipt page with transaction details and a receipt of the purchase. You can use the analytics.js library to send the ecommerce data from the "Thank You" page to Google Analytics.

There are two types of ecommerce data you can send using analytics.js: transaction and item data.

Transaction Data

A transaction represents the entire transaction that occurs on your site, and contains the following values:

Key Value Type Required Description
id text Yes The transaction ID. (e.g. 1234)
affiliation text No The store or affiliation from which this transaction occurred (e.g. Acme Clothing).
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.
shipping currency No Specifies the total shipping cost of the transaction. (e.g. 5)
tax currency No Specifies the total tax of the transaction. (e.g. 1.29)

Item Data

An item represents the individual products that were in the shopping cart, and contains the following values:

Key Value Type Required Description
id text Yes The transaction ID. This ID is what links items to the transactions to which they belong. (e.g. 1234)
name text Yes The item name. (e.g. Fluffy Pink Bunnies)
sku text No Specifies the SKU or item code. (e.g. SKU47)
category text No The category to which the item belongs (e.g. Party Toys)
price currency No The individual, unit, price for each item. (e.g. 11.99)
quantity integer No The number of units purchased in the transaction. If a non-integer value is passed into this field (e.g. 1.5), it will be rounded to the closest integer value.

Implementation

You typically implement ecommerce measurement once the user has completed the checkout process. This generally occurs on the "Thank You" page. Once you have, and are ready to send ecommerce data to Google Analytics, there are a couple of steps you need to go through:

Load the Ecommerce Plugin

To reduce the size of the analytics.js library, ecommerce measurement 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 ecommerce plugin, use the following command:

ga('require', 'ecommerce');

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

Once loaded, a couple of new commands specific to ecommerce measurement will be added to the default tracker.

Adding a Transaction

Once the plugin has been loaded, it creates a transparent shopping cart object. You can add transaction and item data to the shopping cart, and once fully configured, you send all the data at once.

You add transaction data to the shopping cart using the ecommerce:addTransaction command:

ga('ecommerce:addTransaction', {
  'id': '1234',                     // Transaction ID. Required.
  'affiliation': 'Acme Clothing',   // Affiliation or store name.
  'revenue': '11.99',               // Grand Total.
  'shipping': '5',                  // Shipping.
  'tax': '1.29'                     // Tax.
});

Adding Items

Next, to add items to the shopping cart, you use the ecommerce:addItem command:

ga('ecommerce:addItem', {
  'id': '1234',                     // Transaction ID. Required.
  'name': 'Fluffy Pink Bunnies',    // Product name. Required.
  'sku': 'DD23444',                 // SKU/code.
  'category': 'Party Toys',         // Category or variation.
  'price': '11.99',                 // Unit price.
  'quantity': '1'                   // Quantity.
});

Sending Data

Finally, once you have configured all your ecommerce data in the shopping cart, you send the data to Google Analytics using the ecommerce:send command:

ga('ecommerce:send');

This command will go through each transaction and item in the shopping cart and send the respective data to Google Analytics. Once complete, the shopping cart is cleared and ready to send data for a new transaction. If a previous ecommerce:send command was issued, only new transaction and item data will be sent.

Clearing Data

If you need to manually clear the shopping cart of all transactions and items, you use the following command:

ga('ecommerce:clear');

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 as well as individual products.

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.

To set the local currency of a particular transaction and all its items, you only need to specify the currency for the transaction:

ga('ecommerce:addTransaction', {
  'id': '1234',
  'affiliation': 'Acme Clothing',
  'revenue': '11.99',
  'shipping': '5',
  'tax': '1.29',
  'currency': 'EUR'  // local currency code.
});

Finally, you can also specify the currency per item:

  ga('ecommerce:addItem', {
    'id': '1234',
    'name': 'Fluffy Pink Bunnies',
    'sku': 'DD23444',
    'category': 'Party Toys',
    'price': '11.99',
    'quantity': '1',
    'currency': 'GBP' // local currency code.
  });

Multiple Tracker Support

You can also use the ecommerce plugin if you have implemented multiple (named) trackers on your page. The plugin works exactly the same as the default tracker, except that the format is: trackerName.pluginName:method. For example if you created a tracker named myTracker:

ga('create', 'UA-XXXXX-Y', 'auto', {'name': 'myTracker'});

You would then load the ecommerce plugin for that named tracker using:

ga('myTracker.require', 'ecommerce');

The to send a transaction, you can create a transaction object and pass it to the named tracker as follows:

var transaction = {
  'id': '1234',                    // Transaction ID.
  'affiliation': 'Acme Clothing',  // Affiliation or store name.
  'revenue': '11.99',              // Grand Total.
  'shipping': '5' ,                // Shipping.
  'tax': '1.29'                    // Tax.
};

ga('myTracker.ecommerce:addTransaction', transaction);

Using this syntax, the transaction object can be used on multiple trackers.

Finally you would send the transaction data as follows:

ga('myTracker.ecommerce:send');

Example

Most ecommerce sites perform transactions on the server, while the analytics.js library sends data to Google Analytics from the browser. So a little bit of coordination is required between server and client to properly send ecommerce data to Google Analytics.

Most ecommerce sites render their "Thank You" page using a server-side templating engine. In this case, you would add the ecommerce measurement code to the server-side template, and use server logic to dynamically write the ecommerce data values to the final page. Here is an example of how this would look in PHP.

In PHP, you typically would have some representation of the ecommerce data. In this example, the data is stored in an associative array:

<?php
// Transaction Data
$trans = array('id'=>'1234', 'affiliation'=>'Acme Clothing',
               'revenue'=>'11.99', 'shipping'=>'5', 'tax'=>'1.29');

// List of Items Purchased.
$items = array(
  array('sku'=>'SDFSDF', 'name'=>'Shoes', 'category'=>'Footwear', 'price'=>'100', 'quantity'=>'1'),
  array('sku'=>'123DSW', 'name'=>'Sandals', 'category'=>'Footwear', 'price'=>'87', 'quantity'=>'1'),
  array('sku'=>'UHDF93', 'name'=>'Socks', 'category'=>'Footwear', 'price'=>'5.99', 'quantity'=>'2')
);
?>

The first step is to write some logic to transform the ecommerce data into the JavaScript string required by analytics.js:

<?php
// Function to return the JavaScript representation of a TransactionData object.
function getTransactionJs(&$trans) {
  return <<<HTML
ga('ecommerce:addTransaction', {
  'id': '{$trans['id']}',
  'affiliation': '{$trans['affiliation']}',
  'revenue': '{$trans['revenue']}',
  'shipping': '{$trans['shipping']}',
  'tax': '{$trans['tax']}'
});
HTML;
}

// Function to return the JavaScript representation of an ItemData object.
function getItemJs(&$transId, &$item) {
  return <<<HTML
ga('ecommerce:addItem', {
  'id': '$transId',
  'name': '{$item['name']}',
  'sku': '{$item['sku']}',
  'category': '{$item['category']}',
  'price': '{$item['price']}',
  'quantity': '{$item['quantity']}'
});
HTML;
}
?>

Then in the <script> tag you would add the additional PHP logic to dynamically output the transaction and item data:

<!-- Begin HTML -->
<script>
ga('require', 'ecommerce');

<?php
echo getTransactionJs($trans);

foreach ($items as &$item) {
  echo getItemJs($trans['id'], $item);
}
?>

ga('ecommerce:send');
</script>

Once the PHP script is done executing, the transaction and item data required by analytics.js will be printed to the page. Once the JavaScript on the page is rendered in the browser, all the ecommerce data will be sent to Google Analytics.

Currency Types

The default currency type can be configured through the Management Interface. When you send currency values using analytics.js, the value represents the total value of a currency.

A decimal point can be used as a delimiter between the whole and fractional portion of the currency. The precision is up to 6 decimal places. The following is valid for a currency field:

1000.000001

Once the value is sent to Google Analytics, all text is removed up until the first digit, the - character or the . (decimal) character. So:

$-55.00

will become:

-55.00