Google Analytics custom dimensions

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

Example: A travel website would like to capture destinations in Google Analytics reports. Create a custom dimension called "destination" to capture the locations that are being viewed and booked.

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 and then Property and then Custom Definitions and then 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 and then Property and then Custom Definitions and then 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 some value off 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: It could be an element ID on the page, a value that is generated when an event occurs (e.g. a timer event), or it could be some piece of text found in the web page's URL.

For the next example, we shall assume that the value we want to use is found in the page URL as a fragment; a string of text that shows up after the octothorpe symbol (#) at the end of the URL. Here's some URLs that our example web site might generate:

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

We need to tell Tag Manager to capture the URL fragments, put that value 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, navigate to Variables and then User-Defined Variables and then New.
  2. Select URL for the variable type.
  3. On the Variable Configuration page, set the Component Type to Fragment.
  4. Name the variable, e.g. "URL Fragment Variable".
  5. 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 Universal Analytics tags that are already setup in Google Tag Manager.

For each analytics tag you have set up in Google Tag Manager:

  1. Open the tag for editing and navigate to More settings and then Custom Dimensions.
  2. Click +Add Custom Dimension
  3. Enter the Index value that you captured in step 1.
  4. For Dimension Value, enter the name of the variable that you created in step 2.
  5. Click Save.
  6. Publish your container for the changes to take effect.

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 tracking codes. 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 and then Property and then Custom Definitions and then 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, navigate to Variables and then User-Defined Variables and then New.
  2. Select Data Layer Variable for the variable type.
  3. Set the Data Layer Variable Name text field to destination.
  4. Name the variable, e.g. "destination data layer variable".
  5. 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 Universal Analytics tags that are already setup in Google Tag Manager.

For each Universal Analytics tag you have set up in Google Tag Manager that should track this custom dimension:

  1. Open the tag for editing and navigate to More settings and then Custom Dimensions.
  2. Click +Add Custom Dimension.
  3. Enter the Index value that you captured in step 1.
  4. For Dimension Value, enter the name of the variable that you created in step 2.
  5. Click Save.
  6. Publish your container for the changes to take effect.
Was this article helpful?
How can we improve it?