What is a Custom Dimension?

With Custom Dimensions you can assign any custom data to your visitors or actions (like pages, events, …) and then visualize the reports of how many visits, conversions, pageviews, etc. there were for each Custom Dimension. They are similar to Custom Variables see the comparison of Custom Dimensions and Custom Variables.

Installing Custom Dimensions

The Custom Dimensions plugin is available on the Piwik Marketplace for free. To install the plugin follow these steps:

  • Log in as a Super User
  • Go to “Administration” by clicking the cogwheel icon in the top right
  • Click on the “Marketplace” menu item
  • Find the Custom Dimensions plugin in the list
  • Press “Install”
  • On the next page, press “Activate” (or alternatively: execute the following command ./console plugin:activate CustomDimensions)

Creating Custom Dimensions

To get to the “Manage Custom Dimensions” screen click on the user icon in the top right. There will be a new menu item “Custom Dimensions” in the left menu. They can be edited by anyone having at least Administration access for a specific website. For each website or app different Custom Dimensions can be created.

Managing Custom Dimensions

Before creating a new Custom Dimension you have to choose whether you need a new dimension in scope “Visit” or “Action”.

Custom Dimensions in scope “Visit” can be sent along any tracking request and are stored in the visit of a specific visitor. If you set different values for a given dimension during the lifetime of a visit, the last value set will be used. A typical example could be any device information or the version of the app the visitor is using.

Custom Dimensions in scope ‘Action’ can be sent along any action (page view, download, event, etc.). A typical example would be for example to track a language along any page view, download or event.

Tracking a Custom Dimension

In general you can track any Custom Dimension via the JavaScript Tracker, the PHP Tracker or via the HTTP Tracker API. Some more trackers might support the tracking of Custom Dimensions as well. To find out how to track a specific Custom Dimension the easiest way is to go to the “Manage Custom Dimensions” screen. By clicking on the edit button you will find the tracking instructions:

tracking custom dimensions via javascript or SDK

Alternatively you can find tracking instructions in the Plugin FAQ.

Custom Dimension Reporting

Depending on the scope of a Custom Dimension you can access a report either via the “Visitors” or “Actions” menu in the Dashboard section. The name of the menu item will be the name of your Custom Dimension. Piwik reports all the standard metrics: unique visitors, visits, actions, time on site, bounce rate, exit rate, etc. The available metrics may be different depending on the scope.

custom dimension reporting

Managing Custom Dimensions

We have seen how to create new custom dimensions, how to track their values, and how to view reports. Now let’s learn about other other capabilities.

Using extractions to set a custom dimension value

Extractions may be defined for Custom Dimensions in scope “Action” so that the value is extracted from the Page URL, Page Title or a Page URL query parameter automatically instead of having to set it manually in your website or app.

An example use case could be a Custom Dimension named “Language”. Piwik can automatically extract the language code from the URL during any tracking request (no tracking code is needed in the website or app).

To extract the value from a Page URL or Page Title you need to define a Regular expression with exactly one sub-expression (one ( followed by a )). For example if you want to extract the language en from page_en.html you could define the pattern page_(.{2}).html. Note that the pattern matches the whole page URL or page title.

Multiple extraction rules can be defined for one Dimension so if the first rule doesn’t match it will check the following rules and try to extract the correct value.

custom dimensions extraction rules - content groups

To prevent getting any wrong values we recommend to test the pattern before creating or updating a Custom Dimension with any online Regular Expression testing tool like https://regex101.com/.

Deactivating a Dimension

It is not possible to delete a Dimension, instead they can be deactivated. Once you deactivate a Dimension the links in the menu will disappear, no value will be tracked for this Dimension and no report will be generated for it anymore. Once the Dimension is activated again everything will work as before and previously generated reports as well as raw log data will be still available.

Segmenting a Custom Dimension by Action type

By default a report for a Custom Dimension in scope “Action” will show values across all kinds of actions (page views, events, content tracking, downloads, etc.). If you want the Custom Dimensions report to show values only for a specific type of actions, say “Page views” or “Downloads”, you can create a new segment using “Action Type”:

segmenting action type custom dimensions

Data Limits for Custom Dimensions

Custom Dimensions are useful to track any information related to any action or visitors. Here are some more information about the data limits in use:

  • 5 Custom Dimensions in scope “Action” and 5 Custom Dimensions in scope “Visit” can be used by default. More slots can be made available by changing the schema of the database (schema changes can be slow depending on the size of the database). Learn more.
  • Each value is limited to a length of 255 characters in length
  • Learn more about the Data Limits in Piwik

Learn more

Any questions?

Many answers and more information about Piwik You can find here:

We are social

Follow us: