How to improve Downloads reporting using Action scope Custom Dimensions

The Matomo Pages report shows how many visits and conversions occurred on each page but it does not include context about the actions triggered on the page. This is because when Matomo tracks an action, such as a download, the action is stored separately from the page view.

Similarly, in the Behaviour > Downloads report, you can view the Download URL (the file path or full URL of the download) and the metrics (Unique Downloads, Downloads), but not the page context where the download happened. If the same file (e.g., /invest.pdf) is linked to three different landing pages, the standard Matomo reports do not automatically include which page the visitor was on when they triggered the download.

This guide explains how to link the download action to the page URL, where the download occurred, using an Action scope Custom Dimension. You can use the dimension in a Custom Report to get a detailed view of the page URL, download URL, and the number of unique downloads.

Track download actions with the Page URL

Although the Downloads report is the easiest way to see which files are downloaded the most, you can include the page URL to identify the pages that generate the highest number of downloads.

Create an Action scope Custom Dimension

1. Navigate to Matomo settings (Administration) > Measurables > Custom Dimensions.
2. Create a new Action Custom Dimension with an identifiable name, e.g., Page Downloads.
3. Select the Active checkbox to enable the dimension.
4. If a download link opens in a new tab or window, Matomo will capture the URL of that new tab (for example, the direct file URL such as /invest.pdf). If you want to capture the page URL where the download link was clicked, you need to prevent the automatic navigation and record the page URL before starting the download.
5. If the download occurs in the same tab without opening a new window, you can configure the Custom Dimension to extract the value directly from the Page URL or Page Title.
   
6. When the action occurs, Matomo extracts and passes these values into the custom dimension.
7. Click Create to save.

Set the custom dimension in your website code

In your website code, you need to set the newly-added Action scope Custom Dimension at the moment the download link is clicked.

For example, the code snippet below stops the browser from navigating immediately, captures the current page URL as a Custom Dimension and triggers the file download. As a result, the download action is logged in Matomo together with the page URL where it happened.

//EXAMPLE CODE
<a href="invest.pdf" onclick="event.preventDefault();
  _paq.push(['setCustomDimension', 12, window.location.href]);
  _paq.push(['trackEvent', 'Download', 'File', 'invest.pdf']);

  const link = document.createElement('a');
  link.href = 'invest.pdf'; link.download = 'invest.pdf';
  document.body.appendChild(link); 
  link.click();
  document.body.removeChild(link);">
  Download</a>

Note: The new dimension must be manually set in your website code when the download click occurs.

Create a Custom Report

In the next step, you can build a new Custom Report to include the Page URL or Page Title Action scope Custom Dimension.

1. Navigate to Matomo > Custom Reports > Manage Reports and click Create New Report.
2. Select the newly-created custom dimension e.g., Page Downloads.
3. Select the second dimension as Download URL.
4. For the metrics, choose Unique Download URLs.
5. Click Preview Report to check the report structure is correct.
   
6. Click Create New Report to save.

This report shows which pages triggered a download, the download URL, and number of unique downloads. Over time, you will be able to identify the pages that initiate the most downloads, allowing you to optimise the pages with less engagement and downloads.

When you need to track actions in connection with a specific page URL or event, use an Action-scope dimension. Each action stores its own value, meaning you can accurately link downloads, clicks, or other events to the exact page where they occurred.

Learn more about Visit and Action Custom Dimensions.