This article is about Google Analytics 4 properties. If you're using a Universal Analytics property, refer to the Universal Analytics section of this help center.

[GA4] Custom dimensions and metrics

Create new dimensions and metrics from event parameters

You can set up custom dimensions and metrics that get their values from the event parameters that you collect for your property. For example, let's say that you collect the following event each time a visitor to your website reads an article.

gtag('event','read_article', {
    "author":"Bill Q",
    "title":"How to Build a Backpack",
    "number_of_pages":2,
});

You can create an Author dimension that gets its values from the author parameter and an Article_Length metric that gets its value from the number_of_pages parameter.

Event and user scope

A custom dimension has either an event scope or user scope.

  • Event scope: In the example above, you would create the Author dimension to have an event scope.
  • User scope: Create user-scoped custom dimensions to identify static or slowly changing attributes of your users, such as "spender=true", "profession=engineer", or "favorite_team=Real Madrid".
    Never include personally identifiable information such as names, social security numbers, or email addresses, even in hashed form.

A custom metric always has an event scope.

Limits

You can create up to

  • 50 custom dimensions and 50 custom metrics per property
  • 25 uniquely named user-scoped custom dimensions

If you have reached your quota but need to create new custom dimensions and/or metrics, you can archive the ones you are no longer using.

To see the total number of custom dimensions and metrics you've created, click Custom definitions under Configure (in the left navigation), then click Quota information (top right).

Create a custom dimension

You need Edit permission to create custom dimensions.

Click Custom definitions under Configure (in the left navigation), then click Create custom dimensions:

  1. Enter Dimension name.
  2. Select a Scope from the drop-down menu. ("Event" or "User")
  3. Enter a Description for your custom dimension.
  4. Select an Event parameter from the list or enter the name of a parameter you'll collect in the future.
  5. Click Save.
You will see a value of "not set" for a custom dimension during the first 48 hours.

Create a custom metric

You need Edit permission to create custom metrics.

Click Custom definitions under Configure (in the left navigation), click the Custom metrics tab, then click Create custom metrics:

  1. Enter Metric name.
  2. Enter a Description for your custom metric.
  3. Select an Event parameter from the list or enter the name of a parameter you'll collect in the future.
  4. Choose a Unit of measurement from the drop-down menu.
  5. Click Save.
It takes 24-48 hours for custom metrics to be populated with data.

Edit a custom dimension or metric

You need Edit permission to edit custom dimensions and metrics.
  1. Click Custom definitions under Configure (in the left navigation)
  2. In the row for the dimension or metric, click More, then click Edit.
  3. Make the changes you want, then click Save.

Archive a custom dimension or metric

If you need to create new custom dimensions and/or metrics but you have reached your limit, you can archive ones you are no longer using in order to free up quota.

  1. Click Custom definitions under Configure (in the left navigation)
  2. In the row for the dimension or metric, click More, then Archive.
This change can't be undone and the corresponding data can't be restored.

Deprecation of custom parameter reporting

With event-scoped custom dimensions and metrics, parameters are identified for property-wide dimensions and metrics, allowing you to create a single dimension or metric based on a parameter and report on it for as many events as you wish. Previously with custom-parameter reporting, parameters were identified for individual events. Consequently, if you wanted to report on the same parameter for five different events, you had to use five of your 100 limit.

With the deprecation of custom-parameter reporting, Analytics has preserved historical event-scoped aggregates, and new aggregates seamlessly extend that historical data. In cases where a parameter was registered for multiple events, Analytics disambiguates between them by assigning a dimension/metric name that includes the currently assigned event name (e.g., “custom_dimension_name [event_name]”).

As a best practice, you should remove duplicate custom dimensions and metrics that were registered across multiple events to help preserve quota.

User-scoped custom dimensions eliminate the need for you to think about "slots." User properties become aliases for user-scoped custom dimension slots, allowing developers to focus on tracking meaningfully named data points without having to associate each data point with an arbitrary slot number.

Was this helpful?
How can we improve it?
Search
Clear search
Close search
Google apps
Main menu
Search Help Center
true
69256
false