Creating a Custom Dimension

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.

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

tracking custom dimensions via javascript or SDK

Managing a custom dimension

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

Check out our FAQ section for more details on how to use URL extractions with Custom Dimensions.

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.