How do I measure my single-page websites and apps with Matomo?

In recent years, single-page websites and web applications have become increasingly prevalent. However, accurately tracking the performance and user behavior of these applications is essential for success. Measuring data for single-page applications (SPAs) or progressive web apps (PWAs) can pose challenges but is crucial for obtaining meaningful and accurate insights.

Fortunately this process can be greatly simplified using the Matomo Tag Manager using the built in History Change trigger. For an SPA / PWA we usually need the combination of the Pageview and History Change triggers. By using both, we are capturing the initial visit (triggering the Pageview) and every time they navigate within the page (triggering a History Change) Together, they should add up to the correct number of visits.

How to setup the History Change trigger to track Single Page Applications

  1. In your Matomo Tag Manager container, navigate to Triggers and click « Create new Trigger ».
  2. Select the « History Change » trigger under the « User Engagement » section.
  3. Give your trigger a name, for example « History Change ».
  4. Click « Create New Trigger ».
  5. Create another trigger, this time selecting « Pageview » for the trigger type.
  6. Select the « Pageview » trigger under the « Pageview » section.
  7. Give your trigger a name, for example « Pageview ».
  8. Click « Create New Trigger ».
  9. Next, navigate to Tags and click « Create New Tag ».
  10. Select « Matomo Analytics » as the Tag type.
  11. In the « Configure what this tag should do » section, set the Tracking type to « Pageview »:
  12. Set the Custom Title to {{PageTitle}} and Custom URL to {{PageOrigin}}/{{PageHash}} if your SPA or PWA has a # in the URL to navigate to different pages. Otherwise, set it as {{PageUrl}}
  13. Under the option « Execute this tag when any of these triggers are triggered », select the « History Change » and « Pageview » triggers that we created.
  14. Use the Preview/Debug mode to test and ensure that your Triggers & Tag are working as expected.
  15. Once you’ve confirmed that the Trigger and Tag are working as expected, publish the changes so that they’re deployed to your website.

Congratulations! You have successfully configured Pageview tracking for your Single Page Application using the Matomo Tag Manager.

In case your Single Page Application incorporates multiple types of History Changes, you might notice multiple Pageview tracking requests each time a page is viewed. To address this, you can refer to our FAQ on how to restrict the History Change trigger. Follow the steps outlined here to resolve this issue.

For those who are using the standard JavaScript implementation of Matomo’s tracking code, we have comprehensive developer documentation available. Learn how to effectively track Single Page Applications using Matomo Analytics by visiting our guide on How to track single-page websites and web applications using Matomo Analytics.

Keep up the great work and enjoy tracking your Single Page Application with Matomo!