How do I use Extractions to track action data with Custom Dimensions?

One of the key features of Custom Dimensions is the ability to track custom data associated with actions such as page views. Often this requires you to add custom code to your site or make use of a tag manager. However, it is also possible to collect data directly from a Page URL, Page Parameters or Page Titles with the help of Matomo’s built-in Extraction feature.

Every site is unique, so the Custom Dimensions and values you choose to focus on will likely vary. Additionally, there may be different methods for collecting the same information depending on how your site is configured. On this page, you’ll find general instructions on how to set up each type of extraction, along with an example of when and how you might use a certain type of extraction.

It is important to remember that Extractions can only be used on Action scoped Custom Dimensions. You can learn more about scopes in the Custom Dimensions guide.

How to Set Up Extractions for Custom Dimension Data

You can set up extractions on the configuration page of the Custom Dimension they are associated with. You can get to your Custom Dimensions by clicking the cog icon in the blue top menu. Once there, find the Websites or Measurables link (the name varies depending on your version of Matomo) in the Main Navigation along the left-hand side and then click on the Custom Dimensions link.

Once on the Custom Dimension page, scroll to the Action Dimensions section. Next either, click the big green button to create a new dimension or click on the edit icon to configure an existing one.

You can find the relevant settings for creating and managing extractions under the Extract Value heading.

Your next steps will vary slightly depending on the type of extraction you require.

How Matomo extracts the value using RegEx

When configuring extractions via the Page URL and Page Title, you will need to use RegEx search patterns. Learning all of the RegEx variables is beyond the scope of this document. However, one important aspect unique to its use with Custom Dimensions for Matomo is that the first expression in a bracket will extract the value to set against the dimension. To provide a couple of examples:

Custom Dimension for Page ID via Page URL

• Website URL Path: /news/780546/new-nightvision-camera/
• RegEx Search Pattern: /news/(.*)/.*/
• Extraction Result: 780546

Custom Dimension for Author Pages via Page Title

• Website Page Title: Posts By Jane Doe
• RegEx Search Pattern: Posts By (.*)
• Extraction Result: Jane Doe

P.S. In some cases you need to make the pattern used for matching lazy (I.e. Non-greedy). This is done by adding a ? after the * in your capture group. For example: /news/(.*?)/.*/

If you are unfamiliar with regular expressions, we highly recommend you learn about regex before using it and always remember to test your RegEx patterns extensively.

Developers Note: You don’t need to escape forward slashes as Matomo does this for you automatically. e.g. use /news/ instead of \/news\/

Page URL Extraction Example

To use the Extraction feature on Page URLs, the data you plan to track needs to be accessible within the URL. An example use case for URL extraction is tracking the language of a visit on a multi-language site. In the following URL structure, the language code for English en is clearly defined:

https://example.com/lang-en/plugin/

In the URL above, the first part contains the domain https://example.com/. This is followed by the section where the language lang- is set with en representing the two-letter language code for English. Finally, the remainder of the path /plugin/ is the specific page someone is viewing. Following that same structure, the equivalent page in French would have the following URL:

https://example.com/lang-fr/plugin/

As these pages share a common structure, you can safely extract the language code with a RegEx (regular expression) pattern targeting the language code. For the example URL structure above, you can use the RegEx pattern /lang-(.*)/.*/ to capture the language code as shown in the screenshot below:

The above regex looks for the initial /lang- prefix within the URL, then the grouped wildcard (.*) extracts the language code to be associated with the custom dimension. Finally, there are two slashes with a wildcard in the middle /.*/ to ensure that the RegEx pattern catches every page with a language prefix.

Once this custom dimension has been created, you can test it by visiting any page following the same URL structure. To confirm that the data is being tracked appropriately, you should head to the Visits Log, find your specific visit and hover over the URL to see any associated Custom Dimensions. In the screenshot below, you can see that the Page Language dimension has been set as equal to en.

This is just one example of a regex pattern in use. It is possible to create pretty advanced patterns depending on your specific URL structure. There is another example of RegEx in use within the Page Title section below.

Page Title Extraction Example

While Page Titles are often unique for each page, they often share partial similarities. For example, you might include the word Blog for every blog post or Members Area for members-only sections of your website. Consider these example page titles for two blog posts:

• “New Smartphone Makes Your Coffee – Tech Articles”
• “Why You Need to Use Analytics – Marketing Articles”

While the first half looks likely to change for every article, there is a clear pattern for the second part of the title which includes the category that the blog post is in, e.g. Tech or Marketing. If this pattern is consistent across the entire site, you could craft a RegEx pattern designed to extract the blog post category. In this case, you might use the following pattern:

.*–\s(.*)\sArticles

Breaking down the individual components in the pattern above .* matches any number of any characters, until the – kicks in looking for the break in the title. Next, the \s represents a space character to avoid unnecessary spaces within the custom dimensions value. Then the grouped wildcard (.*) selects the actual category text, before the final space character \s and Articles closes off the pattern. Therefore, the extracted values from the above RegEx example would be the words shown in bold below:

• “New Smartphone Makes Your Coffee – Tech Articles”
• “Why You Need to Use Analytics – Marketing Articles”

To test this is working, you can visit any pages matching your pattern and then find your pageview within the Visits Log. If you were following the example above, you would see the following when hovering over the page view:

Page Parameter Extraction Example

Page parameters are elements shown at the end of your URL. They often contain arbitrary data for various reasons, some of which you may want to set up Custom Dimensions for. The first parameter within a URL is preceded by a ? and any following parameters are separated with a &.

As an example, some affiliate programs (where people refer traffic to a site for payment) track referrals via query parameters. This would look a little something like the following URL where ref is the query parameter, and affiliate is the parameter value:

https://example.com/plugin/?ref=affiliate

If you were running an affiliate program this way, it could prove useful to create a custom dimension that tracks which page views were referred by affiliates and which affiliates are driving the most traffic.

Parameters are a little easier to configure than Page URLs as they don’t require RegEx. Instead, you just need to specify the parameter that should be tracked.

Once you have set up the match, you can test that it’s working by visiting a URL containing your page parameter and then finding your page view in the Visits Log. Following the example above, you would see the following when hovering over the page view:

More Resources

You can learn more about how to report on and analyse these values in the complete Custom Dimensions guide.