[UA] Universal Analytics custom dimensions

Note: This article is about Universal Analytics (UA). Starting July 1, 2023, standard UA properties will stop processing data (July 1, 2024 for UA 360 properties). If you are still using UA, make the switch to Google Analytics 4 (GA4).

If you require dimension names in Google Analytics that are not included in the default dimensions and metrics, you can define custom dimensions. Use custom dimensions to collect and analyze data that Analytics doesn't automatically capture. You can send values to custom dimensions with a variable that either pulls data from your web page or uses the data layer to pass specific values.

Use a page variable to set custom dimension values

If you need to associate a value from a list to a Google Analytics session, use a lookup table variable in Tag Manager.

Step 1: Create a custom dimension

To create a custom dimension in Google Analytics:

1. Log in to your Google Analytics account.
2. Navigate to Admin Property: Custom Definitions Custom Dimensions.
3. Click +New Custom Dimension.
4. Provide your own value for the Name field and set the Scope menu to the desired value. Ensure that Active is checked.
   Example: Set the Name field to 'destination', and the Scope menu to 'Hit'.
5. Click Create.
6. The dimension number will be found in the code examples shown on the Created Custom Dimension page. Record the dimension number. In this example the dimension's index number is 6:

JavaScript:
var dimensionValue = 'SOME_DIMENSION_VALUE';
ga('set', 'dimension6', dimensionValue);

Android SDK:
String dimensionValue = "SOME_DIMENSION_VALUE";
tracker.set(Fields.customDimension(6), dimensionValue);

iOS SDK:
NSString *dimensionValue = @"SOME_DIMENSION_VALUE";
[tracker set:[GAIFields customDimensionForIndex:6] value:dimensionValue];

You can always find a dimension's index number in Google Analytics on the table of that appears when you navigate to Admin Property: Custom Definitions Custom Dimensions.

Step 2: Set up a Tag Manager variable to capture page values

The next step is to set up a Tag Manager variable that will capture a value from a web page that can be used to populate the value of a custom dimension field. The value that you target could come from a number of different sources: An element ID on the page, a value that is generated when an event occurs (e.g. a timer event), or text found in a URL.

For this example, the required value is found in the page URL as a fragment; a string of text that shows up after the hash symbol (#) at the end of the URL. Examples:

• https://www.example.com/destinations/#paris
• https://www.example.com/destinations/#newyork
• https://www.example.com/destinations/#tokyo

Tag Manager can capture the URL fragment values, put those values into a variable, and then use that variable to provide the value for the custom dimension that we want to work with:

1. In Tag Manager, click Variables.
2. Under User-Defined Variables, click New.
3. Click Variable Configuration and select URL as the variable type.
4. On the Variable Configuration page, set the Component Type to Fragment.
5. Name the variable, e.g. "URL Fragment Variable".
6. Click Save.

Step 3: Enable custom dimensions in your Universal Analytics tags

The final step is to enable custom dimensions in your Google Analytics Settings variable:

1. Click Variables and then select your Google Analytics Settings variable.
2. Open the tag for editing and navigate to More settings Custom Dimensions.
3. Click +Add Custom Dimension
4. Enter the Index value that you captured in step 1.
5. For Dimension Value, use the variable selector icon to select the name of the variable that you created in step 2.
6. Click Save.

Set custom dimension values from the data layer

The data layer is the best method for ensuring consistent results in your reports, because you retain full control of the values that are passed to your tags. In this example, dataLayer.push() is used on a website to add a destination value to the data layer when a button is clicked:

<button onclick="dataLayer.push({'destination': 'paris'});">
  Book this trip to Paris!
</button>

To use Tag Manager to send this value to Google Analytics as a custom dimension, use a data layer variable and then apply the custom dimension to the appropriate Google Analytics tags already deployed on your website.

Step 1: Create a custom dimension

To create a custom dimension in Google Analytics:

1. Log in to your Google Analytics account.
2. Navigate to Admin Property column: Custom Definitions Custom Dimensions.
3. Click +New Custom Dimension.
4. Provide your own value for the Name field and set the Scope menu to the desired value. Ensure that Active is checked.
   Example: Set the Name field to 'Destination', and the Scope menu to 'Hit'.
5. Click Create.
6. The dimension number will be found in the code examples shown on the Created Custom Dimension page. Record the dimension number. In this example the dimension's index number is 6:

JavaScript:
var dimensionValue = 'SOME_DIMENSION_VALUE';
ga('set', 'dimension6', dimensionValue);

Android SDK:
String dimensionValue = "SOME_DIMENSION_VALUE";
tracker.set(Fields.customDimension(6), dimensionValue);

iOS SDK:
NSString *dimensionValue = @"SOME_DIMENSION_VALUE";
[tracker set:[GAIFields customDimensionForIndex:6] value:dimensionValue];

Step 2: Create a data layer variable

The next step is to create a variable that will capture the correct data layer values:

1. In Tag Manager, click Variables.
2. Under User-Defined Variables, click New.
3. Select Data Layer Variable for the variable type.
4. Set the Data Layer Variable Name text field to destination.
5. Name the variable, e.g. "destination data layer variable".
6. Click Save.

Step 3: Enable a custom dimension in your Universal Analytics tags

The final setup piece is to enable a custom dimension in your Google Analytics Settings variable:

1. Click Variables and then click on your Google Analytics Settings variable.
2. Click Variable Configuration.
3. Click More settings Custom Dimensions.
4. Click +Add Custom Dimension.
5. Enter the Index value that you captured in step 1.
6. For Dimension Value, enter the name of the variable that you created in step 2.
7. Click Save.
8. Publish your container for the changes to take effect.

If you have not yet set up your Universal Analytics tags to use the Google Analytics Settings variable, it is recommended that you do so. A Google Analytics Settings variable can simplify configuration changes from a single variable shared across multiple tags. However, if you need to apply custom dimensions to only a specific Universal Analytics tag, you can use the Enable overriding settings in this tag checkbox to expose the More Settings options.