What is a Tag Manager?

Matomo Tag Manager lets you manage all your tracking and marketing tags in one easy to use place. Tags are also known as snippets or pixels. Such tags are typically JavaScript code or HTML and let you integrate various features into your site in just a few clicks, for example: Analytics, Conversion Tracking, Exit popups and surveys, Remarketing, Social widgets, Affiliates, Ads, and more.

It makes your life easier when you want to modify any of these snippets on your website as you will no longer need a developer to make the needed changes for you. Instead of waiting for someone to make these changes and to deploy your website, you can now easily make the needed changes yourself.

Learn more now by watching the Tag Manager training videos!

How can I get the Matomo Tag Manager?

If you don’t have a running Matomo, first install Matomo. Then you can activate the Tag Manager either through the top menu “Tag Manager” or by going to “Administration => Plugins”.

The Tag Manager is also available on the Matomo Cloud.

Watch the Tag Manager training videos!

How do I can configure the available environments?

Environments let you deploy different versions of a container to different environments. For example you may first want to deploy a specific version to your development environment, then to the test or staging environment before you publish a container on the “live” environment.

A user with super user access can configure the list of available environments in the plugin settings by going to “Administration > System > General settings”.

How do I block custom templates that let Matomo admins run JavaScript on the website like “Custom HTML” or “Custom JS Function”?

Disabling “Custom Templates” can improve the security on your website. When you configure a trigger, tag, or a variable, some of them may allow a Matomo user to enter HTML or JavaScript which will be executed on your website. Entering custom code cannot only break the container in case there is an error, but also allows them to execute any JavaScript code on your website. This can be misused to steal for example sensitive information on your website. If you do not want to allow your team members to enter any JS code, you can disable these templates by going to “Administration => General Settings”. There you can disable them in one click under the “Tag Manager” category.

How do I trigger a tag when any DOM element which matches a CSS selector is clicked?

A frequent use case is that we want to trigger a specific action when one element of the page is clicked. And often these elements may not have a specific ID or CSS class, and the only way to match these elements is by using their CSS selector.

In this FAQ we’ll show you how to use Matomo Tag Manager to trigger a tag when one element matching a CSS selector is clicked. We’ll use this technique with the use case of tracking custom events in Matomo when specific elements of the page are clicked, in our example tracking clicks on 1st level titles (h1).

Create the trigger

Fist, we create the trigger that listens to clicks and specifies the CSS selector:

  • In Matomo Tag Manager click on “Triggers” in the left menu.
  • Click “Create a new trigger”.
  • Select “All Elements Click (Triggered when any element is clicked)”.
  • In this example we’ll trigger on a click on all H1 title elements, so we name the trigger Clicked on H1.
  • Under “Only trigger when” select “Click element Matches the CSS selector”.
  • In the text field, enter the CSS selector that matches the element. In our example we’ll simply enter h1 so any click on a H1 element will trigger.

Note: there is also the option “not matches the CSS selector”.

How to find the CSS selector for a given element of the page?

You can easily find the CSS selector for any element in the page using your web browser. For example in Firefox, you can right-click on your element and select “Inspect element”. Then within the “Inspector” panel which shows the DOM tree, right-click on the element and click on “Copy > CSS selector”. Then you can paste the value in the “Click element Matches the CSS selector” field in Matomo Tag Manager.

Create the tag

Once you have created the Trigger, the next step is to create a Tag.

  • In Matomo Tag Manager click on “Tags” in the left menu.
  • Click “Create a new Tag”.
  • Select the tag you wish to create, for example “Custom HTML”, “Matomo Analytics” or any other tag. In our example we’ll use “Matomo Analytics” since we want to track an event in Matomo Analytics whenever any H1 title element is clicked.
  • Give the tag a clear name. In our example we name it Track event when H1 title is clicked.
  • In our case we want to track a custom event. Under “Tracking Type” we select Event.
  • Next we configure the Event to track in Matomo: we set “Event Category” as Title and “Event Action” as clicked.
  • It is also possible to get the value of the clicked element (for example the text value). In our case we’ll want to track as the “Event Name” the actual text of the H1 title that was clicked, so we set “Event Name” to {{ClickText}}.
  • Click “Create new tag”.

Publish the tag

  • Once the tag is created, the next step is to publish the changes. Click on “Publish” in the left menu.
  • Name the version and click “Create new version and publish release”.

Now whenever a visitor will click on any H1 title in your page, an event will be tracked in Matomo. This is just an example which you can adapt to your own use cases by changing the CSS selector on which the click trigger will be activated.

Screenshot of the “Create a new Tag” page in our example:

How do I block certain tags, triggers, or variables?

If you self host Matomo, you can block the usage of any tag, trigger, or variable through your “config/config.ini.php” file like this:

disable_tags[] = “CustomImage”
disable_triggers[] = “DataLayer”
disable_variables[] = “DomElement”
disable_variables[] = “Cookie”

How do I use variables within the Custom HTML tag?

When you define the content of a Custom HTML, you can access the content of any variable within the container through curly brackets. You can assign the variables to a JavaScript variable, to a CSS style, and use it within HTML:

    // correct
    var myVariable = {{PageUrl}};
    var screenWidth = {{ScreenWidth}};
    var pageWidth = myVariable + screenWidth;

    // not correct (do not put quotes around it)
    var myVariable = '{{PageUrl}}';
    // not correct (do not put two variables next to each other)
    var pageWidth = {{PageUrl}}{{ScreenWidth}};

    // correct (can only be used as a value)
    body {
        width: {{ScreenWidth}};

    // not correct
    body {
        {{myVar}}: 15px;

<div>{{PageUrl}} <a href="{{PageUrl}}">Click Me</a></div>

Not sure about the name of a variable? Simply click on the icon next to the text field and a variable selector will open and automatically insert the needed placeholder for the variable.

What is the CSS style value “mTmKpwoqM”?

If you assign a variable as part of a CSS style, the resulted value may be “mTmKpwoqM” if the variable has not returned any value. For example you may notice a body{ color: mTmKpwoqM; }. This value was chosen to keep your CSS syntax “valid” and so you can find this FAQ article.

How do I track Page Scroll with Matomo Tag Manager?

Tracking the page scroll percentage in Matomo Tag Manager can be done using an Event using a specific trigger that was designed for exactly this purpose.

  1. Create a new tag.

  2. Select Matomo Analytics as the Tag Type

  3. Select the Tracking Type as Event with the Event Categories, Action and Name with your chosen values (For example using 50 for 50% vertical scroll depth):

  4. Next, scroll down and click Create a new trigger now

  5. Then scroll down and select Scroll Reach

  6. Rename the Trigger to your desired Scroll Percentage (50% in this example), set the Scroll Match Type to the type of scroll you want it to trigger at(Vertical in this example) and change the Percentage to the percentage you want this tag to fire at:

  7. Scroll down and click Create New Trigger, and then click Create New Tag.

  8. Publish the changes to your Matomo Tag Manager Container on your website.

  9. (Optional) Use the Matomo Tag Manager preview to test if the Tag is fired or not or go to your website to track your own visit and confirm that the Event is tracked in the Matomo Visit Log.

Congratulations! You’ve now successfully setup Matomo Tag Manager to track Scroll Percentage for your website.

Who can create custom templates like “Custom HTML” or “Custom JS Function”?

During the beta of the tag manager, all admins and super users can create tags, triggers, and variables that execute custom JavaScript on your website. As this could break some features of your website or be misused to steal sensitive information, you may want to disable these features. When the Tag Manager is out of beta, there will be new permissions available so you can grant only certain Matomo users access to these templates. For example only to developers.

How do I track Ecommerce interactions using the Tag Manager data layer?

When implementing Matomo Ecommerce tracking on a website with the most flexibility, it can be recommended to leverage the Tag Manager data layer. This works in a similar way to Google Tag Manager (GTM).

Here are the steps to follow to implement Ecommerce Tracking using the data layer:

Step 1: Create a “Data-Layer” variable eg named PurchaseInfo whose “data layer variable name” is ecommerce.purchase.

Step 2: Create a “Custom Event” trigger which triggers when the Event Name is purchase.

Step 3: Create a Custom HTML tag that fires on this “Custom Event” trigger to track your Ecommerce interaction. For example to track an Ecommerce order you would write:

window._paq = window._paq || [];
var purchaseInfo = {{PurchaseInfo}};
  purchaseInfo.id, // (required) Unique Order ID
  purchaseInfo.revenue, // (required) Order Revenue grand total (includes tax, shipping, and subtracted discount)
  purchaseInfo.orderSubTotal, // (optional) Order sub total (excludes shipping)
  (purchaseInfo.tax || 0), // (optional) Tax amount
  (purchaseInfo.shipping || 0), // (optional) Shipping amount
  (purchaseInfo.discount || false) // (optional) Discount offered (set to false for unspecified parameter)

Step 4: Finally, within your ecommerce backend website/app itself (not within the tag manager), trigger the tag manager event like this in JavaScript:

window._mtm = window._mtm || [];
'event': 'purchase',
'ecommerce': {
  'purchase': {
    'id': 'dynamic value',
    'revenue': 'dynamic value',
    'orderSubTotal': 'dynamic value',
    'tax': 'dynamic value',
    'shipping': 'dynamic value',
    'discount': 'dynamic value',

and replace dynamic value with the actual value for this commerce interaction. This tag manager event purchase will then trigger the custom HTML tag which will in turn, track the Ecommerce interaction in Matomo, using your Data layer’s dynamic variables.

Please note that if you are using the Matomo Tag Manager within Matomo for WordPress and you are wanting to track WooCommerce, Easy Digital Downloads or MemberPress, then you don’t need to do any of this as our plugin does all of this for you. For this to work make sure you have the “Ecommerce” setting enabled in the Matomo Analytics tracking settings within your WordPress.

How do I track my staging/dev/production websites automatically using the same Tag Manager container?

When you’re tracking multiple different environments, for example a Staging, Development or Production (Live) website, using the same Tag Manager Container can simplify your testing and container deployment strategy.

This FAQ assumes that you already have a Tag Manager container setup with a “Matomo Configuration” variable. If you don’t yet have a Tag Manager container setup, you can follow the steps in our Tag Manager User Guide

With Matomo Tag Manager, the Site ID that is used for the container to send tracking data to Matomo is determined by the “Matomo Analytics” variable.
The Site ID can be set automatically with an Advanced variable using a lookup table that can be used to set the Matomo Site ID based on the URL/Hostname of the website where the container is published. This can make deployments between Testing and Production environments easier.

To set this up with Matomo Tag Manager, you can follow these steps:

  1. Create each “Website” you wish to track as its own measurable in Matomo (For example a “Measurable/Website” for each Staging, Dev or Production site)

  2. Create a “Lookup Table” as explained in our Tag Manager User Guide setting each hostname/URL to the URL of your different environments. Be sure to set the value of each URL to the correct Site ID for each environment

  3. Change the Site ID configured in your “Matomo Configuration” variable to the new Lookup Table variable that was just created, for example {{SiteID}}

  4. Deploy the different “Environments” you wish to track to each applicable website. For example the “Staging” environment tracking code should be deployed to your “Staging” website and the “Dev” environment to your development website.

    • For example the “Live” tag manager code will be something like container_eKkj8u2C.js and the “Staging” tag manager code will be something like container_eKkj8u2C_staging_13f53cfa9b905e5dc5654e48.js
      (This is generated automatically when selecting the environment you wish to use)
  5. Deploy any changes you wish to test to the correct “Environment” that has been configured for that website environment

You can find out more about deploying changes to your Tag Manager container in this section of our Tag Manager User Guide.

How do I get the click triggers to only trigger on left, middle or right click?

By default, a click trigger in Matomo Tag Manager will fire a tag whenever a visitor clicks on the left, middle or right button.

Please refer to the steps below on how to get clicks only triggered on left, middle or right click.

  • In Matomo Tag Manager click on “Triggers” in the left menu.
  • Click “Create a new trigger”.
  • Select a click trigger, for example “All Elements Click”.
  • Under “Only trigger when” select “Click Button” – “Equals”.
  • In the text field, enter which click button you want to trigger on (“left”, “middle” or “right”). In our example, we’ll enter right so it will only trigger on any right click.

Note: there is also an option “not equals” to not fire the trigger for a specific click button.

What are the possible values for click button text?

  • left
  • middle
  • right

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

In order to set the User ID using Matomo Tag Manager, we will need to pass the User ID from our website to the Matomo Tag Manager data layer.

Before we begin, you need to have some way to assign the User ID to a variable in your website.
Once you have this setup, then you can proceed with the steps below.

Setting up User ID using the Matomo Tag Manager:

1) First we need to declare the Matomo Tag Manager data layer variable in our website with the following:

var _mtm = _mtm || []; 

2) Next we need to push the User ID that we gather from our website to the MTM data layer:

_mtm.push({'uid':'unique_user_id_here' });
// Replacing unique_user_id_here with the variable that you define in your website code for the User ID

For more information on generating a User ID please see our guide here: User ID

3) Next we will create a new datalayer variable in the Matomo Tag Manager

Go to Tag Manager > Select the Website you wish to create the variable for > Select “Variables” in the lower left menu > click “Create New Variable” > and select “Data-Layer”

Next, give it the name uid and a Data Layer Variable Name uid

And click “Create New Variable”

4) Next we will use this new data layer variable to set the User ID in your Matomo Configuration variable in Matomo Tag Manager

Click on “Variables” in the left menu and find your main “Matomo Configuration” variable in the list and click on the “Edit” button.
Scroll down and click the “Choose a variable” button and select the uid (Type: DataLayer) variable from the list

5) Verify that User ID is tracked

Once you’ve setup the uid variable using the steps above, publish the changes to your MTM container.

Then, go to your website while logged in to generate a tracking request
(You may need to refresh the page or clear your browser cache to ensure that the new MTM container is loaded, and ensure that your traffic is not excluded from tracking)

Then go to Matomo, open “Visitors > Visits log”, select Today in the calendar, and check that your visit was tracked with the User ID

You are now successfully tracking User IDs in Matomo using the Matomo Tag Manager and data layer!!

For more information on setting up Matomo Tag Manager in your website, see our Matomo Tag Manager guide.

How do I use the Matomo Tag Manager with SharePoint Classic sites?

If you’re using SharePoint Classic sites, you can setup Matomo Tag Manager by following the instructions in the article Setup Matomo Tag Manager to the classic SharePoint site collections. The solution described in the article involves running this third-party PowerShell script to automatically add the Tag Manager container code to your SharePoint sites.

See also Is Matomo compatible with Microsoft SharePoint Online (O365 Analytics) and/or SharePoint On-Premises?

Important note: The links above contain information and resources that are neither maintained nor endorsed by the Matomo Team. The use of third party extensions is at your own risk.

The recommended method for tracking goal conversions is to use the Goal Triggers that can be setup when creating a Goal as explained in the Goal Tracking User Guide

However, in some cases it won’t be possible to track a goal conversion using the URL of the page (For example when a link opens the page in an iFrame).
In such a case we can use the Matomo Tag Manager to track the goal conversion for specific links, or for links that contain specific parameters or strings.

Let’s take an example link that a visitor may click: example.com/my-goal (This is just an example, your URL can contain a simple path as shown here, or a more complex one such as example.com/my-goal?success=1)

  1. Create your Goal in Matomo and make a note of the Goal ID
  2. Create a Matomo Tag Manager Trigger with the following settings:

    “All Links Click” as the trigger type with name being for example “Signup Link Trigger”

    And then add the following to the trigger conditions:

    Clicks > “Click Destination URL contains my-goal”
    (If you have other URLs that contain this string, then you may need to add additional conditions to only trigger on these specific URLs such as a regular expression/regex)
    Please note that this trigger will only fire if all of the conditions specified here are matched, so you will not be able to add each unique call to action link as a trigger.

    Optional: If you only wish this goal to be triggered from a specific page on the website, you can add an additional trigger (Lets say for example if we only wanted to track this goal conversion from a specific section of our website, such as the “shop” section):

    Page Variables > “Page URL equals https://example.com/shop”

  3. Create a new “Matomo Analytics” tag with name “Signup Link Tag”
    Tracking Type: Goal
    Goal ID: The Goal ID we created in step 1
    And configure the tag the Execute when the “Signup Link Trigger” is triggered

  4. Test the new Tag and Trigger using the preview mode on the page you wish to use it to ensure that the goal is being tracked correctly.

  5. Once tested, you can publish the container to your Live container version.

How long will the container JavaScript files be cached for in visitors’ browsers? (js/container_*.js files)

When you use Matomo Tag Manager and people visit your website, each visitor’s browser will download the “JavaScript container file” from Matomo. This container file name looks like analytics.example.com/js/container_*******.js. This file includes the Tag Manager JavaScript logic as well as your container’s logic (tags, triggers, etc.). The browser will transfer the file and the size would typically between 20kb and 70kb compressed (gzip).

This static JavaScript file will be cached in the browser for a certain duration.

How long will the container_*.js file be cached for?

  • If you’re using Matomo Self-Hosted, the cache duration depends on how your web server (hosting Matomo) is configured. See below for how to check the current value in your web server.

  • If you’re using the Matomo Cloud service, then the container files are cached for 8 days on visitors browsers.

This means that after you make a change to the container, it will take up to 8 days for the file to refresh in returning visitors’ browsers.

Checking how long your container files are cached for

You can manually check how long the container files are cached for, by using the Developer Tools panel in your browser, and going to the “Network” panel, and searching for “container”. You can then click on the container_*******.js file, and check the “Cache-control” header (where the value is the file cache duration in seconds).

For example on Firefox here is what it looks like on a Matomo instance where the cache is set to 8 days:

Why is debug console not loading for me?

Matomo Tag Manager provides you the ability to debug your website to test before pushing any changes to live. After enabling the preview, you need to specify the URL to debug and it will open the URL and load a debug console on the entered URL. Example:

If the above debug console doesn’t load for you, please ensure the following conditions are met.

  1. Check if you are debugging the correct site and the URL you have entered contains the Matomo Tag Manager JS code.
  2. Check if the cookies are allowed. Matomo Tag Manager uses cookies to enable debug view.
  3. Check if pop-ups are allowed. When you enter a URL to debug, Matomo will try to open the URL in a new tab and set a cookie. Please ensure that no pop-ups are blocked.