Custom dimensions and metrics with gtag.js

This guide describes how to send custom dimensions and metrics to Google Analytics.

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, or levels in games.

To send values of custom parameters to Google Analytics, map the parameters to the following custom Google Analytics dimension or metric parameters:

Custom parameter Data type Description
dimension<Index> string Custom dimension parameter ( i.e. dimension3)
metric<Index> string Custom metric parameter ( i.e. metric8)

Configure and send custom dimensions

To send the value of a custom parameter to Google Analytics, you need to map the parameter to a Google Analytics parameter. gtag.js provides the custom_map parameter to map a custom parameter to a custom Google Analytics dimension or metric.

To send a custom dimension to Google Analytics, update the config for your property to set the custom_map parameter for the dimension and then use the custom parameter to send the value of the custom dimension:

// Configures custom dimension<Index> to use the custom parameter
// 'dimension_name' for 'GA_TRACKING_ID', where <Index> is a number
// representing the index of the custom dimension.
gtag('config', 'GA_TRACKING_ID', {
  'custom_map': {'dimension<Index>': 'dimension_name'}
});

// Sends the custom dimension to Google Analytics.
gtag('event', 'any_event_name', {'dimension_name': dimension_value});

Replace 'GA_TRACKING_ID' with your own tracking ID.

For example, the following snippet will send the custom dimension dimension2 with value 12 to Google Analytics:

// Maps 'dimension2' to 'age'.
gtag('config', 'GA_TRACKING_ID', {
  'custom_map': {'dimension2': 'age'}
});

// Sends an event that passes 'age' as a parameter.
gtag('event', 'age_dimension', {'age': 12});

Configure and send custom metrics

To send a custom metric to Google Analytics, update the config for your property to set the custom_map parameter for the metric and then use the custom parameter to send the value of the custom metric:

// Configures custom metric<Index> to use the custom parameter
// 'metric_name' for GA_TRACKING_ID, where <Index> is a number
// representing the index of the custom metric.
gtag('config', 'GA_TRACKING_ID', {
  'custom_map': {'metric<Index>': 'metric_name'}
});

// Sends the custom dimension to Google Analytics.
gtag('event', 'any_event_name', {'metric_name': metric_value});

Replace 'GA_TRACKING_ID' with your own tracking ID.

For example, the following snippet will send the custom metric metric5 with value 1 to Google Analytics:

// Maps 'metric5' to 'avg_page_load_time'.
gtag('config', 'GA_TRACKING_ID', {
  'custom_map': {'metric5': 'avg_page_load_time'}
});

// Sends an event that passes 'avg_page_load_time' as a parameter.
gtag('event', 'load_time_metric', {'avg_page_load_time': 1});

Configure and send custom dimensions and custom metrics

You can update your property's config to map both custom dimensions and custom metrics:

gtag('config', 'GA_TRACKING_ID', {
   'custom_map': {
     'dimension2': 'age',
     'metric5': 'avg_page_load_time'
   }
});

gtag('event', 'foo', {'age': 12, 'avg_page_load_time': 1});