Set up the Matomo Configuration Variable FAQ - Tag Manager

The Matomo Configuration Variable is a key part of Matomo Tag Manager as it stores essential configuration details for tracking on your website or app such as such as your Matomo site ID and URL instance, consent handling preferences, User ID tracking, and more. The variable streamlines the setup process by acting as a reusable reference point for your Matomo instance.

This variable works with Matomo tags and any custom tags that rely on Matomo’s tracking setup. When you create new tags associated with the Matomo Configuration Variable, the tags inherit the correct tracking settings without needing to manually re-enter details. Updates made to the variable automatically apply to all linked tags.

Add the default Matomo Configuration Variable

When you install Matomo Tag Manager for the first time, a default container is automatically generated and includes the Matomo tracking tag, Pageview trigger, and Matomo Configuration Variable.

The auto-generated setup ensures you have a working configuration immediately, with the configuration variable linked to the default tracking tag. This provides the foundational setup for capturing default tracking data such as page views and outlinks.

In Matomo Tag Manager, navigate to Tag Manager > Variables.
Click Create New Variable and select the Matomo Configuration Variable.
Enter Matomo URL and the site ID associated with the website you are tracking.
The options to Enable Link Tracking, Form Tracking, and Media Tracking are selected by default to track clicks on links, form and video and audio interactions.
Click Create New Variable to save.
You can now use this variable for any Matomo-related tracking tags.

The default Matomo Configuration Variable makes it easy for users of all skill levels to get started with tracking right away using the default configuration.

Customise the Matomo Configuration Variable

By modifying the variable, you can customise your setup to align with your tracking needs. The following settings in the Matomo Configuration Variable address specific requirements.

Enable tracking features

Enable file tracking: Tracking file-based applications or intranet resources where users access files via the file:// protocol. Disabled by default to prevent unintended tracking of personal data if someone downloads a file from your website, stores it locally and then opens it with their browser.
Enable cross domain linking: For managing multiple domains (e.g., example.com and example.org) and need to track visitors as they navigate between them. The Cross Domain Linking Timeout determines how long a visitor’s session data is preserved when they navigate between domains. If the visitor loads the linked domain’s page within the defined timeout period, Matomo considers the activity as part of the same session.
Enable do not track: This setting differs from Matomo’s global Do Not Track server setting where it prevents tracking requests from being sent by the browser when DNT is enabled. The global Do Not Track option accepts tracking requests but filters them out on the server.
Disable performance tracking: Stops tracking your site and page performance and technical metrics such as page load time, server time, and DOM completion time will not be available.
Enable JavaScript error tracking: Identify and track JavaScript errors that occur on your website to improve functionality and user experience. When enabled, JS errors are tracked as Events and appear in the Behaviour > Events report.
Enable heartbeat timer: Tracks the time users actively spend viewing a page by sending periodic requests. The heartbeat is triggered when the user switches tabs, closes or navigates to another page after 15 seconds of activity. You can customise the required active time before a heartbeat is sent. When adjusting the timer, note the minimum interval is 5 seconds and the default is 15 seconds.
Track all content impressions: Scans the DOM for content blocks and tracks all impressions once the page has loaded. Useful for content-heavy for pages where all content blocks are equally important.
Track visible content impressions: Scans the DOM for content blocks but only tracks impressions on content in the user’s viewport. This reduces the volume of impressions recorded compared to tracking all content impressions.
Track bots: Track search engine crawlers’ activity on your site and useful for detecting unusual activity or potential security threats by malicious bots or scrapers. Read more about tracking bots in Matomo.

To comply with privacy regulations, the settings for Disable cookies, Require tracking consent, and Require cookie consent help you manage visitors’ consent before tracking or using cookies. Read more about how to configure consent in the Matomo Configuration Variable.

General tracking options

Disable browser feature detection: Browser feature detection provides insights into user environments, such as screen resolution and installed plugins. While these details can help optimise site performance and usability, collecting this information may be considered intrusive under strict privacy laws. Read more about the Browser report.
Disable campaign parameters tracking: Disabling campaign parameters prevents Matomo from attributing visits to marketing campaigns based on query strings like utm_source, utm_medium, or utm_campaign. This means campaign data will not appear in Acquisition > Channels or Campaigns reports.
Domains: Defining domains ensures Matomo accurately distinguishes between internal and external links, preventing unnecessary outlink tracking for subdomains or paths considered part of your site.
Always use sendBeacon: The sendBeacon API ensures that tracking data is sent reliably to Matomo, even when a user navigates away from the page, such as clicking a link or closing a tab. By handling tracking requests in the background, it allows navigation or interactions to proceed without waiting for the tracking request to complete. This setting is particularly useful for sites with frequent outlink interactions, and you want to prevent delays that users might experience when clicking on external links.
Disable always use sendBeacon permanently: Stop using sendBeacon if you are encountering issues with ad blockers or need more control over the timing of tracking requests.
User ID: Assigning a unique User ID allows you to track individual users across multiple sessions and devices, providing a unified view of their interactions.
Custom Dimensions: Set custom dimensions to capture additional context about your visitors or their actions, such as user roles, product categories, or campaign IDs. They can also be used to segment users or analyse performance across custom categories. Each custom dimension has an index that identifies it. When sending a value for a specific custom dimension, you use its corresponding cd parameter in the tracking request.
Register as Default tracker: The Matomo configuration from the container acts as the primary tracker for your site, ensuring that all _paq commands are processed consistently. Enabled by default.
Bundle Tracker: Bundling the tracker into the container removes the need for an additional HTTP request to load the Matomo tracker separately, reducing page load times. Enabled by default.
Tracking Request Target Path: Customising the target path allows flexibility in your tracking setup, such as integrating with proxies or custom endpoints for improved security or to bypass certain restrictions. Default: matomo.php
Append to Tracking URL: Pass additional metadata or parameters for debugging, custom segmentation, or integrations with other systems.
Force Request Method: Force the POST method for larger payloads, such as those containing many custom dimensions or events, as GET requests may hit character limits. Use GET for simpler or smaller payloads where POST isn’t supported.
Custom Request Processing: Developers can implement custom logic for handling tracking requests, such as redirecting requests or adding conditional logic.

Show Advanced settings

Custom Data: Define a name and value to store key-value pairs alongside each tracked event, pageview, or action, e.g., User Type as the name and value {{User Role Variable}}.
Set Download Extensions: Specify the file extensions that Matomo should track as downloads, replacing the default list. Define which file types should be recognised as downloads, such as doc, xls, pdf. If you set doc, xls, Matomo will only track files with these extensions as downloads, removing all previously defined ones.
Add Download Extensions: Add new file extensions to the list of tracked downloads without replacing the existing ones. If you previously set download extensions as doc, xls, pdf and you add the zip download extension here, Matomo will track doc, xls, pdf, and zip as downloads.
Remove Download Extensions: Exclude specific file extensions from being tracked as downloads. Specify the extensions to remove from the existing list. If doc, xls, pdf, zip are currently tracked, and you remove doc, xls, Matomo will only track pdf and zip as downloads.
Set Ignore Classes: Specify CSS classes that Matomo should ignore when tracking link clicks. If a link contains any of the defined classes, Matomo will exclude it from tracking. If you set classA, classB, any links with these classes will be excluded from tracked clicks, e.g., <a href="example.com" class="classA">Click here</a> will not be recorded in Matomo.
Set Referrer Url: Use this setting to override the automatically detected referrer URL with a custom one. This replaces the HTTP-Referer value that Matomo would normally capture. This is useful when tracking user journeys across iframes, redirects, or custom referral scenarios where the detected referrer might be inaccurate or missing. Note: Call this method before trackPageView() to ensure it applies to all tracking requests.

_paq.push(['setReferrerUrl', 'https://example.com/original-page']);
_paq.push(['trackPageView']);

Set API Url: Specify the Matomo HTTP API endpoint that points to the root directory of your Matomo installation, e.g., https://matomo.example.org/ (if Matomo is installed in the root domain); https://example.org/matomo/ (if Matomo is installed in a subdirectory). This setting is only needed if the Page Overlay report is not working due to incorrect API URL detection. In most cases, Matomo automatically determines the correct API URL, so manual configuration is unnecessary.
Set Pageview ID: – Manually define a Pageview ID for tracking the current page instead of using the default one generated by Matomo. This overrides the pageview ID for every call to logPageView(). Useful when you need to assign a specific identifier to a page view for custom tracking purposes. Do not use this in Single Page Applications (SPAs) or any scenario where trackPageView() is called multiple times during a session. This could cause duplicate pageview IDs, leading to inaccurate tracking.
Set Excluded Referrers: Exclude specific referrer domains from being tracked in Matomo. This prevents certain websites from being recorded as referral sources in reports. You can specify a list of hostnames or domains that Matomo should ignore as referrers, e.g., ignore internal domains that falsely appear as referrals) or specific third-party services.
Set Download Classes: By default, Matomo automatically tracks links to known file types (e.g., pdf, ZIPs) as downloads. You can extend this by specifying additional CSS classes to be treated as downloads. Define CSS classes that Matomo should track as downloads, overriding the default settings. This allows you to mark specific elements (such as buttons or links) as downloads, even if they do not point to a file.
Set Link Classes: Matomo automatically tracks external links (outlinks) when they lead to another domain. Extend this tracking by defining additional CSS classes for elements that should be treated as outlinks, even if they don’t fit the default criteria (e.g., JavaScript-based navigation or redirects).
Set campaign name key: Define the URL parameter(s) that Matomo should use to detect campaign names in tracking URLs. This allows Matomo to correctly attribute visits to marketing campaigns. By default, Matomo recognises standard campaign parameters like utm_campaign.
Set campaign keyword name key: Define the URL parameter(s) that Matomo should use to detect campaign keywords in tracking URLs. This ensures that Matomo correctly identifies and reports keyword data for marketing campaigns. By default, Matomo recognises mtm_kwd as the campaign keyword parameter.
Set consent given: Grants tracking consent for the current visitor, allowing Matomo to track their actions. This consent applies only for the current session and will be lost once the visitor closes their browser or starts a new session. This function temporarily enables tracking after the user consents. consent must be granted again in the next browser session. To persist consent across sessions, use Remember Consent Given instead.
Remember consent given: Grants tracking consent in a browser cookie, ensuring that Matomo remembers consent on future visits. This means visitors do not need to provide consent again in each session. When enabled, you do not need to use the Set consent given option separately.
Expire consent: Specify a time limit for how long Matomo should remember a visitor’s consent before requiring them to opt in again. If no expiry time is set, Matomo stores consent for 30 years or until the user clears cookies. The expiration is based on the browser’s stored cookies and applies only if Remember consent given is used.
Forget consent given: Removes the visitor’s stored tracking consent, requiring them to opt in again before Matomo tracks their actions. This applies whether consent was given for the session only or stored in a cookie for future visits.
Discard HashTag: Removes URL hash fragments (e.g., #section) from tracked URLs in Matomo. This prevents hash-based anchors from affecting how pageviews are recorded. When enabled, Matomo ignores the portion of a URL after #, treating all versions of the same URL as a single pageview.
Set query params to exclude from URL: Define query parameters that Matomo should remove from tracked URLs for cleaner and more consistent reporting. Matomo will strip the specified query parameters before storing URLs in reports. If your URLs contain unique tracking parameters: https://example.com/product?id=123&uuid=abcd1234 and https://example.com/product?id=123&uuid=xyz5678, and you exclude uuid, Matomo will track both as: https://example.com/product?id=123.
Set conversion attribution to first referrer: Changes how conversions (goals, Ecommerce sales) are attributed in Matomo by assigning credit to the first referrer instead of the default last referrer. By default, Matomo attributes conversions to the most recent referrer before the conversion. When enabled, Matomo attributes the conversion to the first referrer that brought the visitor to the website, regardless of later visits from other sources.
Set do not track: Control whether Matomo respects the visitor’s Do Not Track (DNT) browser setting, which signals that they do not want their activity tracked. When enabled, Matomo will not track users who have the DNT setting enabled in their browser. If disabled, Matomo will track all visitors, even if they have enabled DNT in their browser.
Set link tracking timer: Defines the delay (in milliseconds) before Matomo tracks a clicked link as an outlink or download. When a visitor clicks a tracked link, Matomo waits for the specified delay before registering the interaction. This delay ensures that tracking requests are sent before the user leaves the page, especially for outlinks and downloads.
Enable kill frame: Enable to prevent Matomo-tracked pages from being embedded within iframes, enhancing security and user experience by blocking clickjacking and unwanted framing. When enabled, Matomo adds a frame-buster script that detects if the page is loaded inside an iframe and forces it to break out.
Enable count sites in pre-rendered state: Determines whether Matomo should track visits when a page is pre-rendered by a browser before the user interacts with it. Some browsers, such as Chrome and Edge, pre-load or pre-render pages in the background when they predict a user might visit them. When enabled, Matomo tracks pre-rendered pages as visits, even if the user never interacts with them. When disabled, Matomo only tracks the visit once the user actively views or interacts with the page.
Set Request Queue Interval: Defines the time interval, in milliseconds, before executing queued tracking requests in Matomo. This determines how long Matomo waits before sending batched requests after they are added to the queue. The interval controls how frequently Matomo processes queued tracking requests. A higher interval allows more requests to be grouped and sent together, reducing network load. The minimum interval is 1000 milliseconds (1 second). The default setting is 2500 milliseconds (2.5 seconds).

Debug and Test

Use Matomo Tag Manager debug tool to test your Matomo Configuration Variable. In Preview mode, you can verify which tags are firing, confirm the configuration variable is applied correctly, and test changes in real-time without affecting live tracking.

If you need to test different configurations, Matomo Tag Manager allows you to create new versions of your container with updated Matomo Configuration Variables. This can be useful when running A/B tests or experimenting with tracking adjustments.

Next FAQ: How do I set the User ID using Matomo Tag Manager?