Matomo Tag Manager

By admin , 22 July, 2026
matomo

Matomo Tag Manager acts as a middle layer between your website and tracking tools.

Instead of adding many scripts directly into your website:

Website code
   |
   ├── Google Analytics script
   ├── Facebook Pixel
   ├── Heatmap script
   ├── Conversion tracking
   └── Custom JavaScript

you add a single Tag Manager container:

Website
   |
   ↓
Matomo Tag Manager container
   |
   ├── Matomo Analytics tracking
   ├── Events
   ├── Goals
   ├── Custom HTML tags
   ├── Marketing tags
   └── Third-party integrations

The tags can then be managed from the Matomo interface.

Main concepts in Matomo Tag Manager

1. Containers

A container is a collection of tags, triggers, and variables for a website or application.

Example:

Container: example.com

Tags:
 - Matomo Pageview Tracker
 - Download Tracking
 - Contact Form Event
 - Video Tracking

Triggers:
 - All Pages
 - Button Click
 - Form Submission

Variables:
 - Page URL
 - User ID
 - Product ID

The container generates a JavaScript snippet that is installed on your website.

2. Tags

A tag is a piece of code that performs an action.

Examples:

Matomo tracking tag

Tracks page views:

_paq.push(['trackPageView']);

Event tracking tag

Tracks a button click:

_paq.push([
  'trackEvent',
  'Downloads',
  'PDF',
  'Annual Report'
]);

Custom HTML tag

Runs custom JavaScript, for example:

<script>
console.log("Visitor interaction recorded");
</script>

3. Triggers

Triggers define when a tag should run.

Examples:

Page view trigger

Run on every page:

Trigger:
All Pages

Button click trigger

Run when a visitor clicks:

Trigger:
Click → Download button

Form submission trigger

Run when:

Form ID = contact-form

4. Variables

Variables store information used by tags and triggers.

Examples:

Page URL
Page Title
User ID
Cookie value
Click text
CSS selector

Example:

A variable could capture:

Button text:
"Download PDF"

and send:

Event Category:
Downloads

Event Action:
Button Click

Event Name:
Download PDF

Benefits of Matomo Tag Manager

1. Less developer dependency

Marketing and analytics teams can add tracking without requesting code changes.

Example:

Before:

Marketing request
        ↓
Developer ticket
        ↓
Code change
        ↓
Deployment
        ↓
Tracking works

With Tag Manager:

Create tag
     ↓
Test
     ↓
Publish
     ↓
Tracking works

2. Better control over privacy

Unlike many third-party tag managers, Matomo Tag Manager can run entirely within your own infrastructure.

Advantages:

  • Data stays under your control.
  • No mandatory dependency on external advertising platforms.
  • Easier GDPR/privacy compliance management.
  • Works well with self-hosted Matomo.

3. Easier event tracking

Common events can be configured without editing templates:

  • Downloads
  • Video plays
  • Outbound links
  • Button clicks
  • Form submissions
  • Scroll depth
  • Ecommerce interactions

4. Version control and testing

Matomo Tag Manager provides:

  • Preview mode
  • Debug mode
  • Published versions
  • Rollback capability

Example workflow:

Create tag
    ↓
Preview
    ↓
Test on staging
    ↓
Publish version 12
    ↓
Rollback if needed

Matomo Tag Manager with Drupal

For Drupal websites, the usual setup is:

Drupal
 |
 | Matomo module
 |
 | Loads Tag Manager container
 |
 ↓
Matomo Tag Manager
 |
 ├── Page tracking
 ├── Event tracking
 ├── Forms
 ├── Downloads
 └── Custom analytics

In Drupal's Matomo module:

  • Configure your Matomo URL.
  • Configure your Site ID.
  • Enable the Tag Manager container.
  • Enable "Disable tracking" in Advanced settings.

The reason for enabling Disable tracking is to prevent Drupal from loading the normal Matomo tracking code while allowing the Tag Manager container to control tracking.

When should you use Matomo Tag Manager?

Use it when you need:

✅ Multiple tracking events
✅ Marketing campaign measurement
✅ Custom user interactions
✅ Ecommerce tracking
✅ Less dependence on developers
✅ A privacy-focused analytics workflow

You probably do not need it if:

  • You only need simple page views.
  • You only want visitor counts.
  • You have a small site with no custom tracking requirements.

Recommended Drupal + Matomo architecture

For a professional Drupal site, a clean setup is:

Drupal
 |
 ├── Matomo Module
 |       |
 |       └── Loads Matomo Tag Manager container
 |
 └── Content + user interactions

Matomo Tag Manager
 |
 ├── Page views
 ├── Events
 ├── Downloads
 ├── Forms
 └── Custom analytics

Matomo Server
 |
 └── Database

This keeps Drupal responsible for content management and Matomo Tag Manager responsible for analytics logic.

In the Drupal Matomo module, the option:

Disable tracking
If checked, the tracking code is disabled generally. This may be useful when using Matomo Tag Manager.

means that the Drupal module will stop injecting the normal Matomo JavaScript tracking snippet into your site's pages.

What happens when it is enabled?

Normally, the Drupal Matomo module adds something like this to every page:

<script>
var _paq = window._paq = window._paq || [];
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);

(function() {
  var u="https://your-matomo.example.com/";
  _paq.push(['setTrackerUrl', u+'matomo.php']);
  _paq.push(['setSiteId', '1']);
  var d=document, g=d.createElement('script'),
      s=d.getElementsByTagName('script')[0];
  g.async=true;
  g.src=u+'matomo.js';
  s.parentNode.insertBefore(g,s);
})();
</script>

With Disable tracking enabled, that code is not added.

When should you enable it?

Enable it if:

✅ You are using Matomo Tag Manager to deploy your tracking tags.

The flow becomes:

Drupal
  |
  | (does NOT inject tracking code)
  ↓
Matomo Tag Manager container
  |
  ↓
Matomo tracking tag
  |
  ↓
Matomo server

This avoids having two tracking implementations running at the same time.

When should you leave it unchecked?

Leave it unchecked if:

  • You only installed the Drupal Matomo module.
  • You configured the Matomo site ID and URL in Drupal.
  • You want automatic page-view tracking.
  • You are not using Tag Manager.

Your flow should then be:

Drupal Matomo module
        |
        ↓
Matomo JavaScript tracker
        |
        ↓
Matomo server

Important: Avoid double tracking

A common mistake is:

  1. Enable Drupal Matomo tracking.
  2. Add Matomo Tag Manager container manually.
  3. Both fire.

Result:

  • duplicate page views,
  • inflated visitor counts,
  • duplicate events.

If you use Matomo Tag Manager, the recommended Drupal configuration is usually:

  • ✅ Enable the Matomo module
  • ✅ Enter Matomo URL + Site ID
  • ✅ Enable Tag Manager integration/container
  • ✅ Check Disable tracking
  • ✅ Let Tag Manager handle all tracking tags
Page Term Reference
Journal Records
Technology

Comments