Track Events in Matomo using GTM dataLayer Events and Variables

If you are using Google Tag Manager (GTM), you can configure Matomo Tag Manager to read event data from the GTM data layer to capture detailed interactions without having to recreate tracking configurations in Matomo. You will need to enable the container setting, Actively synchronise from GTM data layer, to synchronise new events pushed to the GTM data layer. This ensures Matomo can capture and process dynamic events from the GTM data layer after the initial page load.

By default, Matomo Tag Manager (MTM) copies any existing values from the Google Tag Manager (GTM) data layer into the MTM data layer when the page loads. With the release of Matomo 5.2.0-b3, a new container setting allows GTM data layer events to be actively synchronised to the MTM data layer. Learn more about how to synchronise events from the GTM dataLayer to the MTM dataLayer.

When GTM initialises on your website, it creates a JavaScript object called the data layer. This object temporarily stores information about visitor interactions on your site, such as button clicks or form submissions. Both GTM and MTM can leverage the data layer to track and analyse the same data for custom reporting.

This guide provides example configurations for tracking GTM Events in Matomo:

1. Track Button Click Events using Variables: Utilise GTM data layer variables to track goal conversions in Matomo.
2. Track Form Submission Events using Variables: Extract event data to enrich your Events report.

How to track GTM Button Click Events using Variables

The following example uses Button Click event tracking to demonstrate how Matomo can utilise the GTM data layer to trigger goal conversions, e.g., when visitors click the Sign Up button.

Step 1: Set up Event tracking in Google Tag Manager

1. In your GTM workspace, add a new Google Analytics: GA4 Event Tag and provide a descriptive name, e.g., Click Sign Up.
2. In the Tag Configuration screen, enter the Event Name, e.g. {{Click ID}}. This defines how to identify the event in your GA Events report.
3. Open the Triggers section and add the Click – All Elements Trigger.
4. To ensure the trigger fires only when the Sign Up button is clicked, specify the condition where Click ID contains signup. This is derived from the data layer structure:
   
5. Save the new configuration and test the setup before publishing.

Step 2: Configure Matomo Tag Manager

The next step is to set up the related Goals in Matomo and then configure Tag Manager to read the event data in the GTM data layer and trigger a goal conversion.

First ensure the Tag Manager container setting, Actively synchronise from the Google Tag Manager data layer is enabled.

Create a Goal

1. Open Matomo > Goals > Manage Goals.
2. Click Add a New Goal and specify how the Goal is triggered, e.g., Send an event.
3. To define the event condition, select the Event Category/Action/Name and the relevant expression where Event Name contains signup. When a visitor clicks the Sign Up button, the event data is pushed to the data layer. Matomo reads the specified event name and triggers the goal conversion.
   
4. Include other optional settings if required and save the new goal.

Create a Data Layer Variable

1. In Matomo Tag Manager, navigate to Variables.
2. Click Create New Variable and choose the Data Layer variable type.
3. Provide a descriptive name to identify the variable, e.g., elementId.
4. Enter the Data Layer Variable Name. In this example, the gtm.elementId is used as it matches the event attribute in the data layer.
5. Save the variable and it can now be used to retrieve information from the GTM data layer.

Create a Custom Event Trigger

1. Navigate to Triggers and click Create New Trigger.
2. Choose the Custom Event Trigger and provide a descriptive name to identify the trigger, e.g., Click Signup.
3. In the section, Configure this trigger, enter the Event Name that is pushed to the data layer. In the GTM data layer example above, the event name is gtm.click.
4. Add a trigger condition to ensure it only fires when the signup button click event is pushed to the data layer. Select the gtm.elementId variable created previously and define the condition as: gtm.elementId equals signup.
   
5. Save the new trigger.

Step 3: Preview and Debug

Finally, test your button click event to ensure that both your GTM and MTM configurations are functioning correctly. You may need to preview and debug each Tag Manager container separately, as it’s not possible to test both containers on the same page simultaneously while unpublished.

1. Trigger the button click event.
2. Use GTM’s Preview Mode to ensure the data layer is populated with the correct values when the Sign Up button is clicked.
3. After publishing the GTM container, you can now debug the Matomo Tag Manager configuration.
4. Use MTM’s Preview Mode to verify the Custom Event Trigger fires when clicking the signup button.
5. Check the data layer variable contains the expected value.
6. Open your browser’s Developer Tools > Network tab.
7. Confirm that a request is made to your Matomo instance (matomo.php) with the correct event parameters (e.g., action name, event category).
8. Log in to your Matomo instance and check the Visits in Real-time report to ensure the goal conversions are recorded.
9. Once you’ve confirmed that everything is working as expected, publish the MTM container.

By following these steps, you can successfully configure event tracking in GTM and set up Matomo Tag Manager to read the GTM data layer and trigger goal conversions.

How to track Form Submissions using Variables

The following example shows how to track subscription order submissions as a custom event in Matomo. This tracking will capture the subscription type (e.g., Premier Plan) from the GTM data layer.

Step 1: Set up Form tracking in Google Tag Manager

1. In your GTM workspace, add a new Google Analytics: GA4 Event Tag and provide a name, e.g., Order Form Submit.
2. In the Tag Configuration screen, enter the Event Name. This defines how to identify the event in your GA Events report.
3. Open the Triggers section and add the Form Submission Trigger.
4. To ensure the trigger fires only when the Order Form is submitted, specify the condition where Form ID contains order-form. This is derived from the HTML element ID.
   
5. Save the new configuration and test the setup before publishing.

Step 2: Configure Matomo Tag Manager

In this step, you will configure Matomo Tag Manager to read the order form submission event in the GTM data layer using a data layer variable.

First ensure the Tag Manager container setting, Actively synchronise from the Google Tag Manager data layer is enabled.

Create a Data Layer Variable

1. In Matomo Tag Manager, navigate to Variables.
2. Click Create New Variable and choose the Data Layer variable type.
3. Provide a descriptive name to identify the variable.
4. Enter the Data Layer Variable Name. This example uses subscription as it matches the event’s attribute in the data layer.
5. Save the variable and it can now be used to retrieve information from the GTM data layer.

Create a Custom Event Trigger

1. Navigate to Triggers and click Create New Trigger.
2. Choose the Custom Event Trigger and provide a descriptive name.
3. In the section, Configure this trigger, enter the Event Name. Using the data layer example above, the event name is orderSubmission.
4. Save the new trigger.

Add a Matomo Analytics Tag

In this setup, the Custom Event Trigger fires when the form submission event data is pushed to the data layer. It executes the tag and records the order form submission as an event including the type of subscription ordered.

1. Navigate to Tags and click Create New Tag.
2. Choose the Matomo Analytics Tag and provide a descriptive name, e.g., Subscriptions ordered.
3. Select the default Matomo Configuration Variable. You can modify the variable’s settings according to your tracking requirements.
4. For the Tracking Type, choose Event.
5. Define the Event as you want it to appear in your Matomo Behaviour > Events reports.
6. For this example, the Event is defined as:
   Event Category: Form Submissions
   Event Action: Order Submit
   Event Name: {{subscription}} to include the type of subscription ordered.
   
7. In the section, Configure when the tag should do this, link the newly-created Custom Event Trigger by selecting it from the drop-down list.
8. Save the new tag.

Add a Custom HTML Tag

This tag will execute when a DOM Ready Trigger fires to detect the form submission and push the event data into the data layer.

1. Navigate to Tags and click Create New Tag.
2. Choose the Custom HTML Tag and provide a descriptive name.
3. In the Custom HTML field, provide the script to push the form data to the data layer. This is an example script, so it must be modified to match your form’s structure and behaviour.

<script>
 // Initialise the dataLayer if not already defined
  window.dataLayer = window.dataLayer || [];

  document.getElementById('order-form').addEventListener('submit', function(event) {
    event.preventDefault(); // Prevent the default form submission behaviour

    // Get the value from the Subscription Type field
    const subscription = document.getElementById('subscription-type').value;

    // Push the value to the dataLayer
    window.dataLayer.push({
      event: 'orderSubmission',
      subscription: subscription,
    });
    // After pushing to the dataLayer, resume the default behaviour
  event.target.submit();
</script>

Set the Position to Head Start. In the section, Configure when the tag should do this, click the link Create a new trigger now and add a DOM Ready Trigger.
Save the trigger and you will be directed back to the tag configuration screen where you can save the new tag.

Step 3: Preview and Debug

Finally, test your the form submission event to ensure that both your GTM and MTM configurations are functioning correctly. You may need to preview and debug each Tag Manager container separately, as it’s not possible to test both containers on the same page simultaneously while unpublished.

1. Trigger the form submission event.
2. Use GTM’s Preview Mode to ensure the data layer is populated with the correct values when the form is submitted.
3. After publishing the GTM container, you can now debug the Matomo Tag Manager configuration.
4. Use MTM’s Preview Mode to verify the Custom Event Trigger fires when submitting the form.
5. Check the data layer variable contains the expected value.
6. Open your browser’s Developer Tools > Network tab.
7. Confirm that a request is made to your Matomo instance (matomo.php) with the correct event parameters.
8. Log in to your Matomo instance and check the Visits in Real-time report to ensure the form event is recorded.
9. Once you’ve confirmed that everything is working as expected, publish the MTM container.

By following these steps, you can successfully configure event tracking in GTM and set up Matomo Tag Manager to read the GTM data layer and capture data from a submitted form.

Best Practices for Integrating the GTM Data Layer with Matomo

A well-structured data layer integration sets the foundation for reliable tracking and simpler maintenance.

• It could be useful to document your data layer structure and keep it updated. Note which events and variables are being pushed from GTM and how they map to your Matomo configuration.
• Set precise trigger conditions in Matomo Tag Manager to capture exactly what you need. For example, if tracking form submissions, specify the exact form ID or class rather than capturing all form events.
• Before deploying, test in debug mode. Use the tag manager’s Preview mode to verify the data passes correctly and the triggers fire as expected.
• Keep your production container clean by removing unused variables and triggers created during testing. This reduces complexity and makes your setup easier to maintain.

Troubleshooting

Explore potential issues that may arise and how to resolve them.

Data Layer variable not capturing data:

• Ensure the variable name in MTM matches the exact structure of the data in the GTM data layer.
• Verify that the data is being pushed to the data layer before the trigger fires in MTM.

Triggers not firing in MTM:

• Check the trigger conditions in MTM align with the data layer values (e.g., event = orderSubmission).
• Ensure no tag priorities or blocking tags are preventing other tags from firing.

Missing data in Matomo:

• Confirm that the tag in MTM is configured to include the correct variables from the data layer.
• Use MTM’s Preview Mode to verify that the data layer values are available at the time the tag is triggered.

MTM not accessing the GTM Data Layer:

• Ensure that the GTM data layer is defined when the page loads.
• Check the MTM container settings are correctly set to access the GTM data layer.
• Confirm the MTM container is correctly added to your site.

Real-time data not appearing in Matomo:

• Verify the correct Matomo server and site configuration is used for your Matomo instance.
• Use the browser’s Developer Tools (Network tab) to ensure requests are being sent to your Matomo instance.

For additional support, you can visit the Matomo community forum to connect with other users and find troubleshooting advice. If you require further assistance, contact Matomo Support for expert help.