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.

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

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

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 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 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 measure, you must also identify the custom metric as a cost and/or revenue metric. When you identify the custom metric as a cost and/or revenue metric, then you can restrict access to it when you configure user roles that restrict access to cost and/or revenue metrics.
  5. Click Save.
It takes 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 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.

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

  1. Click Custom definitions under Configure (in the left navigation)
  2. In the row for the dimension or metric, click More, then Archive.
    You see a list of the other entities in Analytics (e.g., audiences, explorations) that use the custom definition.
This change can't be undone and the corresponding data can't be restored.

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 cannot export invalid audiences to other products (e.g., Google Ads, 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

Similar warnings appear in Explorations for explorations and segments that include archived custom dimensions or metrics. In addition, the dimension and metric lists in Explorations identify archived custom definitions with the same 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 cannot 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 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