Understanding the Matomo Tag Manager Data Layer FAQ - Tag Manager

The Matomo Tag Manager data layer can be used to temporarily store and pass information to Matomo Tag Manager (MTM) about specific actions triggered by visitors on your website. By default, MTM tracks many common interactions like basic pageviews, link clicks, and scroll depth using built-in triggers and variables without having to use the data layer.

However, when you need to track more complex actions or pass information such as transaction details, the data layer becomes necessary. It is a JavaScript object (typically implemented as an array, e.g. window.dataLayer = []) that acts as a structured interface between a website’s front-end and MTM. Developers can push event data and contextual metadata into this central location accessible to Tag Manager.

Each push() to the data layer can include an object describing an event (e.g. event: 'newsletterSignup') along with the relevant parameters (e.g., form id). Tag Manager listens for the event and any conditions applied will determine when the trigger fires the tag.

For Beginners
The data layer is a central place where your website stores important information that Tag Manager can use to trigger tags and track events. Think of it as a digital clipboard. Every time a user interacts with your website like clicking a button, viewing a product, or submitting a form, your website can record details about that action on the clipboard. Tag Manager then reads from the clipboard to decide what to track and when.

The following example shows how to manually add mtm.push() to the web page and how to view the completed event in the ` data layer and Matomo’s Event reports.

How the MTM tracking code works

Before Matomo Tag Manager (MTM) can track any user interactions, it needs to be loaded on the web page you want to track. The MTM tracking code includes a call to _mtm.push() that initialises the data layer and signals when MTM should start listening for events.

Your site-specific MTM tracking code is located in Matomo > Tag Manager > (open container) > Install Code:

<!-- EXAMPLE Default MTM tracking code-->
<script>
  var _mtm = window._mtm = window._mtm || [];
  _mtm.push({'mtm.startTime': (new Date().getTime()), 'event': 'mtm.Start'});
  (function() {
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; g.src='https://cdn.matomo.cloud/mysubdomain.matomo.cloud/container_AbC123.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<!-- End Matomo Tag Manager -->

Creates the data layer

The following steps explain how the MTM tracking code sets up the data layer and why the initial 'mtm.Start' event is important.

var _mtm = window._mtm = window._mtm || []; : Initialises the MTM data layer by creating a global _mtm array if one does not already exist. This array acts as the central location for event data that Matomo Tag Manager reads from.
_mtm.push({'mtm.startTime': (new Date().getTime()), 'event': 'mtm.Start'}); : Pushes an object into the _mtm array containing a default event (event: 'mtm.Start') and a timestamp ('mtm.startTime') marking when the container starts loading.
MTM uses this event to detect when the container loaded but it can be also used for triggering events and tag that depend on the start of MTM.
The function() dynamically loads the container script (container_AbC123.js).
Once loaded, the script reads the _mtm array and executes any tags configured in the container. These tags can be triggered by default events like mtm.Start or custom events such as button clicks or form submissions.

When to use the data layer

Matomo Tag Manager includes built-in triggers for common actions like page views, clicks, and scrolls, which is sufficient for basic tracking. However, the data layer becomes essential when you need to:

Track custom or complex user interactions that are not automatically detected by MTM, such as AJAX form submissions, multi-step form processes, or interactions with third-party embedded content.
Pass structured, dynamic data such as order details, user type, or product information.
Trigger tags based on specific values within a pushed event, for example, firing a tag only if the purchase value exceeds a defined amount or if a custom attribute matches a certain condition.

How to use the data layer

Once MTM is loaded, you can push your own events and data into the _mtm array (the data layer). Each time you push an event into the array, you’re telling MTM that something happened on the website, such as a visitor signing up to a newsletter or completing a purchase. These events can then be used to trigger tags and pass contextual information into your analytics reports.

The following examples show three common use cases: tracking a newsletter signup, tracking a button click, and tracking a completed purchase. They involve pushing an event into the data layer, but differ in complexity and configuration.

If your website includes a form for visitors to sign up for weekly newsletters, Matomo Tag Manager can trigger a tag to log the signup when the form is submitted.

The newsletter signup event is pushed with a simple identifier (event: 'newsletterSignup'). MTM can trigger a tag using just the event name, so no data layer variables are needed unless you want to pass additional information, such as the form’s location or user type.

The example shows _mtm.push() added to the webpage code after the form is successfully submitted:

window._mtm = window._mtm || [];
window._mtm.push({
  event: 'newsletterSignup',
  formLocation: 'homepage',
  userType: 'guest'
});

This pushes an event object into the _mtm data layer. The event name is used to trigger a tag in Matomo Tag Manager via a Custom Event Trigger. The additional properties, such as formLocation and userType, provide extra context that can be accessed using data layer variables if needed.

For example, if userType is set up as a data layer variable, it can be used to segment or filter reports in Matomo based on whether the visitor is a guest or customer (or other defined category). In this example, there is no data layer variable for the event name because it is only used to define the trigger condition.

Configure a Custom Event Trigger to use the event name newsletterSignup (matching the event key used in the _mtm.push() call on the webpage).
Link the trigger to the Matomo Analytics Tag, so the tag fires only when the newsletterSignup event is pushed to the data layer.
Set the Matomo Analytics Tag set to Event tracking type and define the event data to be sent to Matomo for reporting.
View these events in the Visits in Real-time and Visits Log reports, and in Matomo > Behaviour > Events for a more detailed analysis.

If you can’t edit the form’s submission logic, an alternative to using the data layer, is setting up a Click Trigger on the signup button.

Example 2: Tracking button clicks using data attributes

This example shows tracking button clicks using HTML data-* attributes. When a user clicks the button with attributes like data-event="ctaClick" or data-label="Download Guide", these values are passed to Matomo Tag Manager via _mtm.push().

Data layer variables are created to access the value for data-label="Download Guide", and use it to fire off tags based on the event and reuse the contextual data. The setup makes it easy to manage tracking across multiple buttons while capturing structured information for each interaction.

The example shows _mtm.push() added to the webpage code below the button definition:

<button id="download-guide-button">Download Guide</button>

<script>
  document.getElementById('download-guide-button').addEventListener('click', function () {
    window._mtm = window._mtm || [];
    window._mtm.push({
      event: 'ctaClick',
      label: 'Download Guide',
      section: 'homepage'
    });
  });
</script>

This example tracks a click on a specific button and pushes predefined values directly into the data layer.

Configure a Custom Event Trigger to use the event name ctaClick (matching the event name used in the _mtm.push() call – triggered when a button is clicked).
Link the trigger to the Matomo Analytics Tag, so the tag only fires when the ctaClick event is pushed to the data layer.
The button element on the page includes data-* attributes such as data-label="Download Guide" and data-section="homepage". Data layer variables are created in Matomo Tag Manager to access values like label and section when passed into the data layer via _mtm.push(). These variables can be used in the tag to dynamically populate event parameters or apply conditions for more targeted tracking.

Example 3: Tracking a completed purchase

This is a good example of how the data layer can support Ecommerce tracking, where structured and transactional data needs to be captured reliably. Note: Ecommerce tracking must be enabled in Matomo for your website.

When a customer completes a transaction, you may want to send several key details to Matomo, such as order ID, revenue, product list, and discount applied. These values are usually not available directly in the DOM, or are spread across multiple sources. Instead, you can push all relevant information into the data layer the moment the purchase is confirmed. By using data layer variables in Matomo Tag Manager, the Ecommerce order values like orderId and revenue are captured from the event object.

The example shows _mtm.push() added to the order confirmation page. The event details are populated when the order is confirmed.

<script>
  window._mtm = window._mtm || [];
  window._mtm.push({
    event: 'purchaseCompleted',
    orderId: 'ORD12345',
    revenue: 189.99,
    products: [
      { id: 'SKU123', name: 'Backpack', price: 49.99 },
      { id: 'SKU456', name: 'Red_Jacket', price: 140.00 }
    ],
  });
</script>

View the data layer

When data is pushed into the _mtm array, it is important to verify the data layer events are pushed correctly, triggers are evaluating the right conditions, and tags are firing at the right time.

There are two ways to see what’s happening inside the data layer:

Matomo Tag Manager includes a Preview and Debug mode that shows real-time activity for testing triggers, tags, and variables. When an event is pushed to the data layer, you can verify the including events pushed into the data layer.
You can also inspect the data layer directly in your browser. Open your website, right-click anywhere and choose Inspect to open Developer Tools. In the Console tab, type _mtm and press Enter. This will display the current contents of the _mtm array.

How to use both Matomo and Google Tag Manager data layers

Matomo Tag Manager (MTM) and Google Tag Manager (GTM) each use their own data layer arrays: _mtm for MTM and dataLayer for GTM. They can operate side by side when both tag managers are installed on your website.

You can choose to manage them independently and push events separately to each data layer or configure MTM to actively synchronise with the GTM data layer after the initial page load.

When to work with MTM and GTM:

GTM not installed: Use _mtm only for all event tracking.
GTM installed, MTM sync disabled: Push events manually to both dataLayer and _mtm if you want both platforms to track the same interactions.
GTM installed, MTM sync enabled (from Matomo 5.2.0+): Manual pushes to _mtm are optional. MTM automatically listens for and captures new events pushed to dataLayer.

When GTM initialises, it creates a dataLayer object to store interaction data such as button clicks or form submissions. With synchronisation enabled, Matomo can read this data and trigger tags without needing to replicate tracking logic in MTM. Learn more about synchronising events from the GTM data layer.

Note that if you want to migrate from Google Tag Manager to Matomo Tag Manager, our Tag Manager supports data layers written in the Google Tag Manager format. As a result, if your data layer is written as:

<script>
  dataLayer = [{
    'variable-name': 'value'
  }];
</script>

It is supported in the same way as a Matomo data layer.

Learn more about the data layer in this training video

Next steps

Next FAQ: Data layer developer guide