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