[GA4] Custom dimensions and metrics

This article is for anyone who wants to create custom dimensions and metrics from event parameters.

In this article:

• Overview
• Event and user scope
• Limits
• Create a custom dimension
• Create a custom metric
• Edit a custom dimension or metric
• Archive a custom dimension or metric
• Deprecation of custom-parameter reporting

Overview

You can set up custom dimensions and metrics that get their values from the event parameters that you collect for your property.

You don't need to set up custom dimensions and metrics for data collected through automatically collected events, enhanced measurement events, and recommended events.

 

It's also recommended that you don't create custom dimensions that can have a very high number of distinct values, as this can result in data aggregating into the (other) row in Reports. For example, for a high-cardinality dimension like User ID (i.e., for when you want to collect an ID for each distinct user), use the User-ID feature.

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

You can configure your custom dimensions to be either event-scoped or user-scoped.

• Event scope: In the previous example, you would create the Author dimension using event scope.
• User scope: You can 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".

You must always use event scope for custom metrics.

Limits

You can create up to:

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

If you have reached your quota but need to create new custom dimensions and/or metrics, you can archive the ones that 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).

Note: Certain custom dimensions are not available in reporting when combined with demographic information. You may experience thresholding or incompatibility constraints in reporting or with the API when requesting custom dimensions with demographic data.

Create a custom dimension

You need the Editor role to create custom dimensions.

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

1. Enter a 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 (event scope) or User property (user scope) from the list or enter the name of a parameter/property 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 the Editor role 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 a 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.
   When you select Currency as the unit of measurement, you must also identify the custom metric as a cost and/or revenue metric under Data type. When you identify the custom metric as a cost and/or revenue metric, you can restrict access to it when you configure user roles that restrict access to cost and/or revenue metrics.
5. Click Save.

It can take 24-48 hours for custom metrics to be populated with data.

Edit a custom dimension or metric

You need the Editor role to edit custom dimensions or metrics.

1. Click Custom definitions under Configure (in the left navigation).
2. In the row for the dimension or metric, click , 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 quota limit, you can archive ones you are no longer using in order to free up space.

Archiving a custom dimension or metric affects any audiences, explorations, or segments that are based on that dimension or metric.

This change can't be undone and the corresponding data can't be restored.

1. Click Custom definitions under Configure (in the left navigation).
2. In the row for the dimension or metric, click , then Archive.
   A list of the other entities in Analytics (e.g., audiences, explorations) that use the custom definition will appear.

Audiences

When you archive a custom dimension or metric that is used in the definition of an audience, that audience definition becomes invalid and the audience doesn't accumulate any new users.

Historical data for the audience is preserved, but no new data is generated once the audience becomes invalid.

You can't export invalid audiences to other products (e.g., Google Ads, Google Optimize).

If you've previously exported the audience to other products, the audience will continue to function as expected. However, since the audience is not accumulating new users, the user count will drop as the membership duration expires for existing users until the audience contains no users.

If an audience includes an archived custom dimension or metric, you see a warning icon next to the audience name in the audience list:

When you edit the audience definition, you see an additional message that the audience includes an archived custom dimension or metric:

You can't edit audience conditions. To create a version of the audience without the archived custom dimension or metric, you need to create an entirely new audience.

Explorations and segments

Warning icons similar to the ones for archived audiences appear in Explorations for explorations or segments that include archived custom dimensions or metrics. In addition, the dimension and metric lists in Explorations identify archived custom definitions with a warning icon.

As with audiences, explorations and segments with archived custom definitions are invalid and will not load.

If you remove the archived custom definition, then the exploration or segment will load.

While archived custom definitions appear in the dimension and metric lists (with a warning), you can't add them to explorations or segments.

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 quota of 100 custom dimensions and metrics.

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 your 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.