Create a custom dimension

A custom dimension is an additional dimension that you can create to collect and analyze data. A custom dimension can be a user’s email, visitor’s age, blog category, blog author and the like.

In this article, we’ll show you how to create a custom dimension.

Before you start

Now, before you create your first custom dimension, learn about a few things:

• There are two scopes: session and event and we’ll explain it a bit later.
• You can create 25 custom dimensions for each scope and if you need more space, you’ll need to contact us.
• The value of a single custom dimension can be up to 255 characters long. Tracking will fail when this limit is exceeded.
• Once you create a custom dimension you can’t delete it. You can only make it inactive.
• To use the custom dimension you need to modify the tracking code either manually or using a ready-made option in the Piwik PRO tag.
• Custom dimensions are available in core reports as well as custom reports.

About the scope for a custom dimension

The scope may be a bit confusing so we’ll explain it before you start. We’ve got two types of scopes: session and event.

The session scope relates to the whole visit and holds captured custom dimension for the whole session. If during a session the value of a custom dimension will change, Piwik PRO will record the last value. For example, let’s say you’ve created a custom dimension of visitor’s age in the session scope. That’s a good way to do that since the age is not changing during the session. But, let’s say that the visitor first by mistake input the 23 as an age and during the session changed it to 32. In this case, Piwik PRO will capture the last value, which in this case is the number 32.

The event scope relates to events like a page view or downloading a file and holds captured dimension for each event. For example, if you want to record each page view for the author of the blog, you will use the event scope. If you used a session scope, Piwik PRO would overwrite the previous value with each next page view, so you’d you’d be left with the last value only at the end of the visit.

Now let’s move on to creating the custom dimension.

Create a custom dimension

Once you know what information you want to capture from which scope, you can create a custom dimension and set up the tracking. The setup is a few step process, so follow the instructions in this article to stay on the right track.

To create a custom dimension, follow these steps:

1. Go to Menu > Analytics.
2. Navigate to Settings.
3. On the left, click Custom dimensions.
4. Here you can choose the scope for the custom dimension: session or event. Click Add session dimension or Add event dimension.
   

   

   Note: When you use an event dimension and track it with a custom dimension tag, you need to run this tag before the tracking code (Piwik PRO tag). This is because a custom tag needs to send data before a page view is tracked. Read more about setting tag priority.

5. Name the dimension.
6. Optionally, set the extract value if you want Piwik PRO to automatically capture the value from the page URL or page title.
   

   

7. If you’re going to adjust the tracking code manually, copy the code.
   

   

8. Click Save.
9. Once the custom dimension is created, note the tracking ID. You’ll need it to set up tracking in Tag Manager.
   

   

   Note: The value of a single custom dimension can be up to 255 characters long. Tracking will fail when this limit is exceeded.

By default, each new custom dimension is set to be active. However, you can make it inactive at any time.

To make the custom dimension inactive, follow these steps:

1. Go to Menu > Analytics.
2. Navigate to Settings.
3. On the left, click Custom dimensions.
4. Find the custom dimension that you want to work with and on the right, click a three-dot icon.
5. Click Deactivate.
   

   

Set up a variable

In most cases, before modifying the tracking code, you will need to create the variable that will hold and pass information with the value of a custom dimension. For example, we’ve set up a custom dimension for a blog author and we need to pull out information on the author’s name from the blog post.

Using a variable for tracking custom dimension is a solution that works in some cases and  setting a variable differs depending on the website construction. If you need help in finding the best approach for your site, contact us and we’ll help you out. In case you feel confident with setting up a variable, read on.

To set the variable, follow these steps:

1. Go to Menu > Tag Manager.
2. Navigate to Variables.
3. On the left, click Create new variable.
4. Name the variable and click Save.
5. Choose the variable type. In our case, we’ll use the DOM element.
   

   

6. Set up the variable. In our case, we’ll use the CSS selector and add .author. The .author element relates to the HTML element with the .author class used for the blog author on our website.
   

   

7. When you’re done, click Save.

Modify the tracking code

When you have the custom dimension and variable ready, you can modify the tracking code. But no worries, you don’t need to engage the technical person for that, you can simply use our ready-made option available in the Piwik PRO tag in Tag Manager.

To modify the tracking code, follow these steps:

1. Go to Menu > Tag Manager.
2. Navigate to Tags.
3. On the left, click Piwik PRO. This is the tag with the tracking code.
4. In Collect data for custom dimensions, click + Add a dimension.
   

   

5. Enter Dimension ID. You created it under Analytics > Settings > Custom dimensions.
   

   

6. Enter Dimension value. For example, {{ Blog author }}.
   

   

7. When you’re done, click Save.
8. Click Publish.

Check the tracking code and publish

At this point, the best practice is to check if the tracking code catches the new custom dimension. To do that, you can use the debug mode and inspector tool in your browser.

To check the tracking code in debug mode, follow these steps:

1. Go to Menu > Tag Manager.
2. Navigate to Tags.
3. In the top-right corner, click Debug.
4. Your website will open in a new tab with debug mode running.
5. Make an action that triggers capturing the custom dimension. In our example, that will be visiting a blog post.
6. On the right, navigate to Events log.
7. Click the element on the top of the list, for example, stg.timer.
   

   

8. Navigate to Variables.
   

   

9. Scroll down until you see the name and value of your custom dimension.
   

   

By checking the variable in debug mode, we learn if the variable set in Tag Manager is working correctly. Now we need to use the inspector tool in our browser to check if the tracking code sends the dimension with the variable to Piwik PRO.

To check the tracking code with the inspector tool in your browser, follow these steps:

1. Open your website.
2. Open the inspector tool in your browser and navigate to network requests.
3. Make an action that triggers capturing the custom dimension. In our example, that will be visiting a blog post.
4. On the list with network requests, click ppms.php.
   

   

5. On the list with query string parameters, look for the custom dimension. In our case it is the dimension2: John Doe.
   

   

6. When you’re happy with how the tracking code works, go back to Tag Manager and click Publish to make the changes go live.

View the custom dimension report and use custom reports

Once the custom dimension is all set, Piwik PRO will start collecting data about it and present it in the custom dimension report. Additionally, the new dimension will be available in custom reports.

To view the custom dimension report, follow these steps:

1. Go to Menu > Analytics.
2. Navigate to Reports.
3. On the left, click Custom dimensions.
4. Pick the report you want to see.
   

   

To use custom dimensions in custom reports, follow these steps:

1. Go to Menu > Analytics.
2. Navigate to Custom reports.
3. Click Add new report.
4. Pick the report type.
5. Name the report.
6. On the right, click Dimensions.
   

   

7. Scroll down until you see Custom dimensions.
8. Pick the custom dimension you want to use in the custom report.
   

   

9. Continue the setup of your custom report, and when you’re done, click Create report.

Optionally, you can use the core report with custom dimensions as a basis for creating a custom report. To do that, you will need to have an owner account or user account with manage, edit & publish, or edit permissions.

To use the core report as a base for a custom report, follow these steps:

1. Go to Menu > Analytics.
2. Navigate to Reports.
3. On the left, click Custom dimensions.
4. On the right, click Customize.
   

   

5. Customize the report.
   

   

6. When you’re done, click Create report.

You’ll find your customized core report under Menu > Analytics > Custom reports.