Custom Dimensions

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.

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. Matomo (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.

The custom dimension values are also displayed in the Visits Log:

• In the left of each visit in the Visits Log, the Custom Dimensions of scope “Visit” are displayed.
• On hover on each Pageview or Action, the values of your “Page” scope dimensions will be displayed in the tooltip.The custom dimension values are also displayed in the Visitor Profile. On the left, you will find the list of all custom dimensions values that were tracked for this visitor (for all “Visit” scope dimensions).

Installing Custom Dimensions

The Custom Dimensions plugin is available on the Matomo 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, go to “Administration” by clicking the cogwheel 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 ‘Write’ or ‘Admin’ access for a specific website. For each website or app different Custom Dimensions can be created.

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 “Visit” scope dimension during the lifetime of a visit, the last value set (in this visit) 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:

Alternatively you can find tracking instructions in the Plugin FAQ.

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”. Matomo 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 pageen.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.

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”:

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 Matomo

Learn more

• FAQ: What are the advantages of Custom Dimensions over Custom Variables?
• FAQ: How do I add more than the default 5 custom dimensions?
• Tracking guides for Custom Dimensions: JavaScript Tracking Guide and API reference, Tracking API reference