Custom dimensions and metrics with gtag.js

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. This page describes how to send custom dimensions and metrics to Google Analytics.

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 (e.g. dimension3)
metric<Index> string Custom metric parameter (e.g. metric8)

Configure and send custom dimensions

To send the value of a custom parameter to Google Analytics, you need to map a value on your website to a Google Analytics parameter. This can be accomplished using the custom_map parameter.

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_MEASUREMENT_ID', where <Index> is a number
// representing the index of the custom dimension.
gtag('config', 'GA_MEASUREMENT_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_MEASUREMENT_ID' with your own Analytics ID.

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

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

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

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_MEASUREMENT_ID, where <Index> is a number
// representing the index of the custom metric.
gtag('config', 'GA_MEASUREMENT_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_MEASUREMENT_ID' with your own Analytics 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_MEASUREMENT_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_MEASUREMENT_ID', {
   'custom_map': {
     'dimension2': 'age',
     'metric5': 'avg_page_load_time'
   }
});

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