Google Analytics

Custom Dimensions & Metrics - Feature Reference

This document provides a reference for the Custom Dimensions and Metrics feature of the Google Analytics platform.

  1. Overview
  2. Understanding Custom Dimensions and Metrics
    1. Configuration
    2. Collection
      1. Scope and Precedence
    3. Processing
    4. Reporting
  1. Examples
    1. Hit-scoped dimension
    2. Session-scoped dimension
    3. User-scoped dimension
    4. Custom metric
  2. Implementation Considerations
  3. Available Libraries
More

Overview

Custom dimensions and metrics allow you to bring additional data into Google Analytics that can help you answer new questions about how users are interacting with your content.

What are dimensions and metrics?

A metric is a count of some data type, like pageviews, that is summed up across your Google Analytics hits. A metric corresponds to a column in a report. Dimensions allow you to break down a metric by a particular value, like screen views by screen name. Dimensions correspond to the rows in a report.

Google Analytics offers over 200 pre-defined dimensions and metrics that allow you to see how metrics, like pageviews, are distributed across dimensions, like major cities.

Using custom dimensions and metrics, you can define your own dimensions and metrics that enable you to gain new insights into how users are interacting with your content.

Why are custom dimensions and metrics useful?

Custom dimensions and metrics allow you to bring data you might have outside of Google Analytics, like in a CRM system for example, and bring that data into the platform to build new reports that help you answer questions about your content or your business. For example:

  • If you store the gender of signed-in users in a CRM system, you might want to combine that with your Google Analytics data to see pageviews by gender. Using custom dimensions, you could bring gender data for signed-in users into the platform, and create a new report that breaks down pageviews by gender to find see how different types of users experience your content differently.

  • If you're a game developer, metrics like level completions or high scores may be more relevant to you than pre-defined metrics like screen views or avg time on site. By tracking this data with custom metrics, you can keep track progress against your most important metrics in flexible and easy-to-read custom reports.

How are custom dimensions different from custom variables?

Custom dimensions are functionally very similar to custom variables. Both features enable you to group your data in new ways by applying values to hits based on a scope that you define.

The fundamental difference between the two is that custom dimensions are primarily managed on the server side, whereas custom variables are primarily managed on the client side. This has several implications:

  • Less data needs to be sent in each hit. Since the name and scope of your custom dimension is defined in your property settings, only the index and value need to be sent at collection time.
  • Custom dimension definitions are more flexible. Name and scope can be edited in your property settings without necessarily modifying your code. Learn more about how editing custom dimension definitions can affect your reporting.
  • Each property has 20 available custom dimension indices. By contrast, custom variables are managed on the client side in five custom variable "slots" per property.

Currently, custom dimensions and metrics are supported by the Google Analytics SDKs for Android and iOS v2.x. Older versions of the Native App SDKs support custom variables, as does the ga.js Javascript library.

Understanding Custom Dimensions and Metrics

The lifecycle of a custom dimension or metric has four stages:

  • Configuration – you define your custom dimensions and metrics with an index, a name, and other properties like scope.
  • Collection – you send custom dimension and metric values to Google Analytics from your implementation.
  • Processing – your data is processed using your custom dimension and metric definitions and any view (profile) filters.
  • Reporting – you build new reports using your custom dimensions and metrics in the web interface.

Configuration

Before you can send custom dimension and metric values to Google Analytics, they must first be defined in a Google Analytics property. Each Google Analytics property has 20 available indices for custom dimensions, and another 20 indices available for custom metrics.

When you define a custom dimension or metric, you specify its name and other configuration values at a particular index. Custom Dimensions have the following configuration values:

  • Name – the name of the custom dimension as it will appear in your reports.
  • Scope – specifies to which hits the custom dimension will be applied. Learn more about Scope.
  • Active – whether the custom dimension or metric value will be processed. Inactive custom dimensions may still appear in reporting, but their values will not be processed.

Custom metrics have the following configuration values:

  • Name – the name of the custom metric as it will appear in your reports.
  • Type – determines how the custom metric value will be displayed in reports.
  • Minimum / Maximum Value – the minimum and maximum values that will be processed and displayed in your reports.
  • Active – whether the custom metric value will be processed. Inactive custom metrics may still appear in reporting, but their values will not be processed.

Custom dimensions and metrics are defined in the Google Analytics web interface. Learn how to define custom dimensions and metrics.

Once you define a custom dimension or metric, avoid editing name or scope when possible. See Implementation Considerations to learn more about how changes to these values can affect your reporting.

Collection

Custom dimension and metric values are sent to Google Analytics at collection time as a pair of index and value parameters. The index parameter corresponds to the index of the custom dimension or metric defined in the Configuration phase.

Unlike other types of data, custom dimensions and metrics are sent to Google Analytics as parameters attached to other hits, like pageviews, events, or ecommerce transactions. As such, custom dimension or metric values need to be set before a tracking call is made in order for that value to be sent to Google Analytics.

For example, to set a custom dimension value to a screen view in an Android app, your code might look like this:

Tracker tracker = EasyTracker.getTracker();

// Set value for custom dimension at index 1.
tracker.setCustomDimension(1, "Level 1");

// Send the custom dimension value with a screen view hit.
tracker.trackView();

Custom Metric Types

Custom metrics with a type of Integer or Time should be sent using integers, while custom metrics with a type of Currency may be sent as fixed decimal values appropriate to the local currency.

Processing

When custom dimensions are processed, scope determines to which hits a particular custom dimension value will be applied, while view (profile) filters determine which hits and their associated values are ultimately included in Reporting.

Scope and Precedence

Scope determines which hits will be associated with a particular custom dimension value. There are three levels of scope: hit, session, and user:

  • Hit – value is applied to the single hit for which it has been set.
  • Session – value is applied to all hits in a single session.
  • User – value is applied to all hits in current and future sessions, until value changes or custom dimension is made inactive.
Hit-level scope

When a custom dimension has hit-level scope, the value is only applied to the hit with which the value was set. This is demonstrated in Figure A, Figure B, and Figure C below:




Session-level scope

When two values with session scope are set at the same index in a session, the last value set gets precedence and is applied to all hits in that session. In Figure D below, the latest value set overwrites any previous values for that index:






User-level scope

Lastly, if two user-scoped custom dimension values are set within the same session, the last value set gets precedence for the current session, and is applied to future sessions for that user.

In Figure B below, CD value A is applied to all hits in session 2, just like a session-level CD. However in Figure C, unlike with session-level scope, the CD value A continues to be applied to hits in the third session due to CD1 having user-level scope:


Filters

View (Profile) filters can interact with custom dimensions and metrics in several ways.

Custom dimensions and metric values are each associated with the hit with which they were received, regardless of their scope. If that hit is filtered by a view (profile) filter, the custom dimension or metric may also be filtered, depending on its scope:

  1. Hit-scope: Both Custom dimensions with hit scope and custom metrics will be filtered if the hit they are associated with was also filtered.
  2. Session or User-scope: User or session-scoped custom dimensions will not be filtered even if the hit they were attached to is filtered. Their values will still be applied to all hits in the current session, as well as future sessions if the dimension has user scope.

Custom dimensions can also be used to construct view (profile) filters. This will cause hits to be filtered according to the scope of the custom dimension. For example, filtering on a user-scoped custom dimension value would filter current and future sessions from the set of users associated with that value.

Reporting

After the collection, configuration, and other processing stages of the pipeline are complete, custom dimensions and metrics become available via the web reporting interface.

Custom dimensions and metrics are available in custom reports and available for use with advanced segments. Custom dimensions can also be used as secondary dimensions in standard reports.

Examples

The following examples show how custom dimensions and metrics can be used by a mobile game developer to learn about player behavior.

A game developer has recently released a new game for Android.

The current Google Analytics implementation tracks a screen view each time a user plays a level. The developer already knows how many times each level is played. Now they want to answer these more advanced questions:

  1. How many times are easy levels played versus medium or hard levels?
  2. How many levels are played for each day in a 3-day free trial?
  3. How many levels are played by users in the trial versus users who have paid for the app?

To answer these questions, custom dimensions are used to create new groupings of hits, sessions, and users.

Hit-level scope

Let's look at an example of how the game developer can use hit-level custom dimensions to find out how many levels of each difficulty level -- easy, medium, or hard -- were played.

The developer is already tracking the number of times each level is played using screen views. Now they want to know which difficulty is getting played the most.

The report will looks like this:

DifficultyScreen Views
easy 
medium 
hard 

Before using custom dimensions, the developer could see total screen views by level, but they were not able to group those screen views by difficulty.

By using a hit-level custom dimension, the difficulty can be associated with each screen view, allowing reports to include the difficulty being played the most.

Why hit-level scope?

A user may play several levels in the course of one session. Using hit-level scope means that a difficulty value will only be associated with the screen view with which it was sent. This ensures that each level screen view can be associated with a unique difficulty.

Configuration

The first step to implementing a custom dimension is to define it in your property settings in the Admin section of the web interface. For this example, the custom dimension definition looks like this:

Index1
NameDifficulty
ScopeHit
StateActive

Collection

In the game, the developer is already tracking each level with a screen view. In order to associate the difficulty with each level, the custom dimension value must be set just prior to the call to track the screen view.

On Android, the implementation might look like this:

Tracker tracker = EasyTracker.getInstance();  // The Google Analytics tracker.
tracker.setCustomDimension(1, "easy");        // Set the custom dimension value.
tracker.trackView("/level_1/");               // Custom dimension value is sent with this hit.

In this example, the custom dimension is set just before the level screen view is tracked. This associates the difficulty with the screen view and will allow the screen view hits to be grouped by difficulty in reports.

Processing

After the hits are collected and sent to Google Analytics, the data is processed and custom dimension values are applied to hits according to their scope.

For example, the data collected for a single player, with one session, who played 6 levels, looks like this:

userId = 5555
Session 1:
H1: screen_name=/level_1/ cd1_value=easy
H2: screen_name=/level_2/ cd1_value=medium
H3: screen_name=/level_3/ cd1_value=difficult
H4: screen_name=/level_4/ cd1_value=easy
H5: screen_name=/level_5/ cd1_value=medium
H6: screen_name=/level_6/ cd1_value=medium

Note that using hit-level scope ensures each difficulty value is only associated with the screen view with which it was sent.

Reporting

Once processed, because each screen view is associated with its respective difficulty value, a developer can create a report that uses both screen name and difficulty as dimensions, and screen views as a metric:

Screen nameDifficultyScreen views
/level_1/easy1
/level_2/medium1
/level_3/hard1
/level_4/easy1
/level_5/medium1
/level_6/medium1

A custom report can be created that uses Difficulty as a primary dimension to group screen views and find out how many times each difficulty level was played:

DifficultyScreen views
easy2
medium3
hard1

In this report, medium difficulty levels were played the most. This insight is made possible by using hit-level custom dimensions to group screen views.

Session-level scope

Let's now look at an example of how the game developer can use session level custom dimensions to see how many levels are played for each day in a 3-day free trial.

The developer already knows how many times each level is played by tracking a screen view for each level. Now they want to know how many levels were played on each day.

The report the developer wants to create looks like this:

Day of TrialScreen views
Day 1 
Day 2 
Day 3 

By using a session-level custom dimension, the developer can group screen views by the day of the trial and see how that number changes as a user spends more time in the free trial.

Why session-level scope?

You can use session-level scope to efficiently group entire sessions, and all of their component hits, under a single Day of Trial value.

Although hit-level scope could be used to achieve the same functionality, using session-level scope allows you to conveniently set a Day of Trial value using the least amount of additional code.

Configuration

The Day of Trial custom dimension is defined in the property settings section of the web interface with these values:

Index2
NameDay of Trial
ScopeSession
StateActive

Collection

In the game, the developer is already tracking each level with a screen view. In order to associate a day with all the screen views in a session, the custom dimension value only needs to be set once per session.

On Android, the developer would set the custom dimension when the user first starts the game:

Tracker tracker = EasyTracker.getInstance();  // The Google Analytics tracker.
String day = getDayOfTrial();                 // Get the day of the trial.
tracker.setCustomDimension(2, day);           // Set the custom dimension value.
tracker.trackView("/home_screen/");           // Custom dimension value is sent with this hit.

Note that a session-level custom dimension can be set at any time during the session. However in this example, it is simply convenient for the developer to determine the day of trial and set the value accordingly at the start of the session.

Processing

After the hits are collected and sent to Google Analytics, the data is processed and custom dimension values are applied to hits according to their scope.

For example, the data collected for a single player, who played the game twice on the first day, once the second day, and once the third day, looks like this:

userId = 5555
Session 1:
H1: screen_name=/level_1/  cd2_value=1
H2: screen_name=/level_2/
H3: screen_name=/level_2/

Session 2:
H4: screen_name=/level_3/  cd2_value=1
H5: screen_name=/level_4/
H6: screen_name=/level_4/

Session 3:
H1: screen_name=/level_1/  cd2_value=2
H2: screen_name=/level_2/
H3: screen_name=/level_3/

Session 4:
H1: screen_name=/level_3/  cd2_value=3

Note that custom dimension values have only been sent with one screen view per session.

Session-level scope ensures that the Day of Trial value will be associated with all hits in that session, not just the hit it was sent with.

Reporting

After processing, the session-level custom dimension values will be associated with all screen views received in the same session. The developer can now create a report using Day of Trial and screen name as dimensions and screen views as a metric:

Day of TrialScreen nameScreen views
1/level_1/1
1/level_2/2
1/level_3/1
1/level_4/2
2/level_1/1
2/level_2/1
2/level_3/1
3/level_3/1

And finally, to group screen views by day and find out how many levels were played on each day of the trial, the developer can create a custom report that uses Day of Trial as a primary dimension:

Day of TrialScreen views
16
23
31

The data shows that the most levels on the first day and played noticeably fewer levels on days 2 and 3. This insight is made possible by using session-level custom dimensions to group multiple sessions and their component hits by a single value.

User-level scope

Finally, let's look at an example of how the game developer can use user-level custom dimensions to find out how many levels were played by paid users versus free trial users.

As in prior examples, the total number of times each level is being played is already tracked with screen views, but the developer now wants to group screen views by free and paid users.

The report the developer wants to see looks like this:

Player TypeScreen views
Free 
Paid 

Using a user-level custom dimension, the developer can get this data by associating all screen views of a particular user, across their current and future sessions, with a Player Type value.

Why user-level scope?

User-level scope allows you to conveniently group all of a user's component sessions and hits by a single value. It is ideal for values that don't change often for a particular user, like Player Type in this example.

Note that although this same functionality could be achieved with hit or session-level scope, user-level scope provides the most convenient solution with the least amount of code.

Configuration

The Player Type custom dimension is defined in the management section of the web interface with these values:

Index3
NamePlayer Type
ScopeUser
StateActive

Collection

As in previous examples, the developer is already tracking each level with a screen view. To group those screen views by Player Type, the developer only needs to set the Player Type dimension when the user starts the app, and a second time if a user subsequently pays to access the full version of the app.

On Android, the developer would set the custom dimension when the user first starts the game:

Tracker tracker = EasyTracker.getInstance();  // The Google Analytics tracker.
tracker.setCustomDimension(3, "Free");        // Set the custom dimension value.
tracker.trackView("/level_1/");               // Custom dimension value is sent with this hit.

The developer would also want to set the custom dimension when the user pays for the full version of the app:

Tracker tracker = EasyTracker.getInstance();
tracker.setCustomDimension(3, "Paid");
tracker.trackView("/level_3/");

Processing

As in previous examples, after data is collected it is processed and custom dimension values are applied to hits according to their scope.

For example, the data collected for a single player who played the game twice as a free user and once as a paid user would look like this:

userId = 5555
Session 1:
H2: screen_name=/level_1/ cd3_value=free
H3: screen_name=/level_2/

Session 2:
H1: screen_name=/level_2/
H2: screen_name=/level_3/
H3: screen_name=/level_3/

Session 3:
H1: screen_name=/level_3/ cd3_value=paid
H2: screen_name=/level_4/

Note that the free value set in session 1 applies to all hits in that session as well as session 2, until the new value of paid is set in session 3.

Reporting

After processing, Player Type custom dimension values will be associated with the sessions in which they were set, as well as any future sessions and hits.

The developer can now create a report using Player Type and screen name as dimensions and screen views as a metric:

Player TypeScreen nameScreen views
Free/level_1/1
Free/level_2/2
Free/level_3/2
Paid/level_3/1
Paid/level_4/1

Finally, to group screen views by Player Type and find out how many levels were played by free versus paid users, the developer can create a custom report that uses Player Type as a primary dimension:

Day of TrialScreen views
Free5
Paid2

The data shows that more levels were played by free users than paid users. This insight is made possible by using user-level custom dimensions to group users and their component sessions and hits by a single value.

Custom Metrics

In the examples above, the game developer has been tracking each play of a level as a screen view. In each of the reports generated, the screen view metric is used to represent a player's attempt to complete a level.

However, the developer also wants to know the completion rate of each level.

To determine the rate of completion, the developer will use a new custom metric called Level Completions and compare it to screen views for each level.

The report the developer wants looks like this:

Screen nameScreen viewsLevel Completions
/level_1/  
/level_2/  
/level_3/  

Why use a custom metric?

In many cases, you'll have the option to use events, screen views, and/or a custom metric to track your most important metrics. However, custom metrics can produce more flexible and more readable custom reports and as such are a convenient way to track your most important metrics.

In this example, level completions could not be tracked as a screen view without double counting the number of screen views per levels, so you'd want to find another option.

Although an event could be used on its own, due to their hierarchical nature it would be difficult to build the above report combining screen views and level completions under a single dimension.

Due to the above limitations, and because level completions is such an important metric to this developer, it's most convenient to track level completions as a custom metric.

Configuration

The Level Completions custom metric is defined in the management section of the web interface with these values:

Index1
NameLevel Completions
StateActive

Note that unlike custom dimensions, custom metric definitions do not include a scope. Custom metrics have an implicit hit-level scope.

Collection

The developer is already tracking the start of each level using a screen view. Now they want to track a level completion using the new custom metric.

As with custom dimensions, custom metrics are sent to Google Analytics as parameters attached to other hits. In order to send the custom metric value, the developer will also need to send an additional hit to record the user completing a level. In this example an event will be fired once the level is completed and a custom metric will be associated with this event.

On Android, that implementation might look like this:

// Called whenever a level is completed.
public void onLevelComplete() {

  // Get the tracker object.
  Tracker tracker = EasyTracker.getTracker();

  // Increment the level completion metric by 1.
  tracker.setCustomMetric(1, 1);

  // Custom metric value is sent attached to the event hit.
  tracker.trackEvent("Level", "Completion");
}

Processing

Before processing, the data for a single player who plays three levels in the game in a single session would look like this:

userId = 5555
Session 1
H1: type=screen_view screen_name=/level_1/
H2: type=event screen_name=/level_1/ cm1_value=1
H3: type=screen_view screen_name=/level_2/
H4: type=screen_view screen_name=/level_2/
H5: type=screen_view screen_name=/level_2/
H6: type=event screen_name=/level_2/ cm1_value=1
H7: type=screen_view screen_name=/level_3/
H8: type=event screen_name=/level_3/ cm1_value=1

Reporting

After processing, the developer can create a report that uses screen name as the dimension and screen views, total events, and level completions as the metric:

Screen nameScreen viewsTotal EventsLevel Completions
/level_1/111
/level_2/311
/level_3/111

Since the developer has tracked level completions as a custom metric, it eliminates any future need to filter the completion events from the total events.

Instead, the developer can easily create the following custom report using the Level Completions custom metric:

Screen nameScreen viewsLevel Completions
/level_1/11
/level_2/31
/level_3/11

The data suggests that level 2 is actually more difficult relative to levels 1 and 3, as it only has a 33% completion rate based on screen views. By tracking level completions as a custom metric, the developer is able to easily answer questions about key metrics and create simplified reports to share with others.

Implementation Considerations

When implementing custom dimensions or metrics, keep the following in mind:

Editing an existing dimension or metric

When you edit the name or scope of an existing custom dimension or metric dimension, your data can be affected in the following ways:

  • Editing name: affects data that has already been processed. Old data will only be accessible using the new name.
  • Editing scope: does not affect data that has already been processed. Only new data will be processed using the new scope.
  • Changing state: the state field determines whether custom dimension or metric values are actually processed. Note that an inactive custom dimension or metric will still appear in your reporting, but because its values were not processed, it will not have any associated data.

Plan ahead when setting scope

When deciding which scope to use for a particular custom dimension, consider how often you expect the value to change. If it's a value that might change many times during a session, like the name of a level in a game, use hit scope and set the value before each hit. On the other hand, a custom dimension like gender could be set at the user level just once. Sending a gender value with each hit would require an unnecessaary amount of work, and configuring a custom dimension that changes often with user scope would incorrectly associate many hits with that value.

Available Libraries

Custom dimensions and metrics are supported by the following libraries:

Google Analytics SDK for Android v2.x
Google Analytics SDK for iOS v2.x

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.