How do I track Single Page Applications using Google Tag Manager with Matomo

Single Page Applications (SPAs) are web applications that load a single HTML page and dynamically update content as visitors interact with the site. Unlike conventional websites that reload the page and request full HTML documents from the server for each navigation, SPAs modify the page’s content without reloading it.

The difference in this behaviour affects how interactions on the SPA are tracked. With a multi page website, pageviews can be automatically tracked whenever a page loads. In SPAs, the browser doesn’t reload the page, so without proper configuration, all SPA activity would be attributed to the initial pageview. This can affect metrics such as time on page, entry and exit pages, and referrer and campaign attribution.

To track SPAs directly in Matomo, read the guides on using Matomo Tag Manager (MTM) or the Matomo tracking code.

If you are using Google Tag Manager (GTM), you can configure it to send virtual pageviews to Matomo either as standard pageviews or as custom events, depending on how you want the data to appear in your reports.

This guide explains how to track virtual pageviews in Matomo as events or pageviews, using GTM.

Before you start

  • Ensure both GTM and MTM container snippets are added to the relevant pages on your website.
  • Installation must be validated and tracking activated.

Configure Google Tag Manager to send pageviews

The following steps explain how to configure GTM to capture virtual pageviews in Matomo as standard pageviews. These pageviews are shown in Matomo’s Behaviour > Pages reports.

This section outlines two options for sending pageviews to Matomo.

  1. Go to Google Tag Manager and install the Matomo Tracking Tag for Matomo Cloud (developed by Matomo) from the Template Gallery.
  2. Enter your Matomo Cloud site ID and tracking URL.
  3. Link the trigger Intialization – All Pages.
  4. Create a Custom HTML tag that uses a History Change trigger and insert the following script:
<script>
  _paq.push(['setCustomUrl', window.location.href]);
  _paq.push(['setDocumentTitle', document.title]);
  _paq.push(['trackPageView']);
</script>

Save and test the tag configuration.

Option 2: Use community developed tags

Matomo Analytics tag developed by Trackify-info

  1. In GTM, install the Matomo Analytics tag developed by Trackify-info from the Template Gallery.
  2. Enter your Matomo instance URL, site ID, and domains being tracked.
  3. Set the Tag Action to Track Pageview.
  4. In Other options, select Track page views manually.
  5. Link the History Change trigger and save the tag configuration.
  6. Create a Custom HTML tag that uses a History Change trigger and insert the following script:
<script>
  _paq.push(['setCustomUrl', window.location.href]);
  _paq.push(['setDocumentTitle', document.title]);
  _paq.push(['trackPageView']);
</script>

Save and test the tag configuration.

Matomo Analytics Configuration tag developed by Data Marketing School

  1. In GTM, install the Matomo Analytics – Configuration tag developed by Data Marketing School from the Template Gallery.
  2. Enter your Matomo instance URL and site ID.
  3. In Other Settings, select Override page URL and choose the built-in variable {{Page URL}}.
  4. Link the tag to the History Change trigger.
  5. Save and test the tag configuration.

Configure Google Tag Manager to send custom events

  1. In Google Tag Manager, go to your workspace and add one of the community developed Matomo Analytics tags from the Template Gallery that support event tracking.
  2. Configure the tag to structure the event based on how you want the data to appear in Matomo reports. For example:
    • Event Category: Virtual Pages
    • Event Action: Views
    • Event Name: {{Page Path}} (GTM built-in variable)
    • Alternatively, use built-in GTM variables to dynamically capture values, e.g., using {{Event}} for the Event Category will be recorded as gtm.historyChange when using the History Change trigger.
  3. Link the tag to the History Change trigger to ensure the virtual pageview is sent to Matomo whenever the SPA route changes.
    define event in google tag manager
  4. Save and test the tag configuration.

Test the configuration

Validate the integration by verifying that tracking is active and data is being sent to Matomo as expected. When testing, make sure tracking is not blocked by consent settings, ad blockers, or browser privacy features.

  1. Open Google Tag Manager’s Preview mode to test the configuration by triggering a route change in your SPA (e.g. navigate between views).
  2. Use Google’s Tag Assistant to check the Matomo tag fires as expected.
  3. Go to your Matomo dashboard and check the Visits in real-time widget or open Visitors > Visits Log report to confirm the pageview or custom event appears. This indicates the virtual pageviews were successfully recorded.
    Pageviews:
    pageviews in matomo
    Custom events:
    record events in matomo
  4. Publish your GTM container.

Troubleshooting

If your virtual pageviews are not appearing in Matomo, check the following:

  1. Ensure you are using the right GTM and MTM container snippet on all relevant pages.
  2. Review the configuration of the community developed Matomo Analytics tag in GTM.
  3. Open your browser’s Developer Tools > Network tab and trigger the virtual pageview. Filter for matomo.php and confirm the request is sent. If no request appears, the tag may not be firing or blocked by browser settings/extensions.
  4. For more details on common tracking issues and how to resolve them, see What should I do if data is not being tracked?

Next steps

For reporting and advanced tracking configurations, explore related topics:

Coming soon! Matomo will be releasing its own official Event tracking tag in GTM.

Previous FAQ: How to track Google Tag Manager Ecommerce Events in Matomo