This guide describes how to send custom dimensions and metrics using analytics.js.

Overview

Custom dimensions and metrics are a powerful way to send custom data to Google Analytics. Web developers can use custom dimensions and metrics to segment and measure differences between: logged in and logged out users, authors of pages, levels in games, or any other business data you have on a page.

For a complete overview on how this feature works, read the Custom Dimensions and Metrics Feature Reference.

You send custom dimension and metric data using either one or both of the following values:

Implementation

You must first configure a custom dimension or metric through the Google Analytics Management Interface. Once configured, the custom dimension or metric will be assigned a unique index that identifies and differentiates one custom dimension or metric from another. You then use the index in the analytics.js library to send data for a particular custom dimension or metric.

Sending Data

Custom dimension or metric data may only be sent with an existing hit. For example, to send a custom dimension for a pageview type hit with the index 15, you would use:

ga('send', 'pageview', {
  'dimension15':  'My Custom Dimension'
});

To send a custom metric for an event type hit with the index 18, you would use:

ga('send', 'event', 'category', 'action', {
  'metric18': 8000
});

If the custom metric is configured to have a currency type, you can send decimal values:

ga('send', 'event', 'category', 'action', {
  'metric19': 24.99
});

In some cases, you might want to send a custom dimension or metric with all the hits on a given page (or for the lifetime of the tracker object). In this case, you can set the custom dimension or metrics using the set command:

ga('set', 'dimension5', 'custom data');

To set values for both a dimension and metric, you can use:

ga('set', {
  'dimension5': 'custom dimension data',
  'metric5': 'custom metric data'
});

Read the Custom Dimensions and Metrics Section in the Field Reference document for the specific format of how to send this data.

Example

A fantastic example of when to use custom dimensions is if you had a content based site with many authors. As an analyst, you might want to understand which authors have the most popular content. To answer this question, you could view a report that compares pageviews by author. Although author data is not available by default in Google Analytics, you can send this data as a custom dimension with each pageview being tracked.

The first step in the solution is to configure a new custom dimension in the management interface. The name should be author and the scope will be of type hit. Once configured, the new custom dimension will be assigned an index. For this example, let's say the index is 5.

Now that the author custom dimension has been configured and assigned an index, it can be used with the analytics.js library to send author data as a custom dimension. For example, if your page is written in PHP, the actual author of the page will probably be stored in a PHP variable like $author. In your PHP template, you can use this author variable to pass the author value to the custom dimension:

ga('send', 'pageview', {
  'dimension5': '<?=$author?>'
});

It's all pretty easy.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.