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.

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:

[TagManager]
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:

<script>
    // 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}};
</script>

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

    // not correct
    body {
        {{myVar}}: 15px;
    }
</style>

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

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:

<script>
window._paq = window._paq || [];
var purchaseInfo = {{PurchaseInfo}};
//console.log(purchaseInfo);
window._paq.push(['trackEcommerceOrder',
  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)
]);
</script>

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 || [];
window._mtm.push({
'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.

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?