[Video] Tracking Single Page Applications (SPA) with Matomo

TRANSCRIPT: Welcome to the next talk, once again by Thomas Persson. Thomas is a business developer at Digitalist Sweden. He has worked with digital analytics since 2010 and contributed to open source projects since 2007. Today, he’ll be discussing how to track single page applications (SPAs) using Matomo, addressing common frustrations and sharing best practices with demos.

Thomas began by defining SPAs, referencing Wikipedia: an SPA is a web application or site that dynamically rewrites the current page with data from the server, rather than loading new pages in the traditional way. A key difference is that the browser doesn’t fully reload — it updates content dynamically. This is common in frameworks like Angular, React, and Vue.js. In fact, Matomo itself is transitioning from Angular to Vue for parts of its interface, such as reports loading without full page refresh.

SPAs pose a challenge for web analytics because traditional page views are tied to browser reload events. In SPAs, these don’t occur. Instead, developers must rely on browser events like history change to detect page transitions. This requires a different approach in Matomo Tag Manager (MTM).

To track SPAs correctly in MTM, the history change trigger must be used instead of the default page view trigger. This allows Matomo to record virtual page views when the URL changes without a full reload. Thomas demonstrated this by comparing two MTM configurations: one using a traditional page view trigger, and another using the history change trigger. He showed how to create a new trigger for history change and link it to a tag configured to send a page view to Matomo.

He then highlighted a common problem: SPA developers often don’t update the page title when content changes. Since Matomo pulls the

<

h2> element instead. Alternatively, you can extract part of the URL to use as a fallback page title.

Another challenge arises when SPAs don’t even rewrite URLs. In those cases, you can simulate tracking by sending relevant DOM elements (like

<

h2>) as pseudo-URLs or titles, allowing for at least partial visibility into user behaviour. Ideally, developers should ensure that the application updates both the page title and the browser history properly, but workarounds like these can be useful when that’s not feasible.

For event tracking (e.g. form submissions or button clicks), Thomas explained how to use MTM’s support for customEvent. He recommended having the SPA application push structured events into Matomo’s data layer using mtm.push(), and then configuring MTM to listen for those events with a custom trigger. This method provides flexibility and keeps tracking logic centralised within the application while still routing through MTM.

He also demonstrated how to capture custom dimensions in Matomo instead of deprecated custom variables. After creating a custom dimension in Matomo, you can pass values into it via MTM by using data layer variables. He walked through an example where custom URL and title values were pushed from the SPA into Matomo using this method.

Toward the end, Thomas discussed the value of using MTM as a middleware rather than sending tracking data directly from the SPA. This gives analysts and implementers more control: you can filter, debug, or modify data without altering the app code. For example, if the SPA has routing logic, you can easily hook into it to dispatch virtual page views via MTM.

In conclusion, Thomas highlighted that while tracking SPAs is complex due to their dynamic nature, Matomo provides tools — especially the Tag Manager — that can be adapted for both ideal and less-than-ideal implementations. Using triggers like history change, custom DOM variables, data layer integration, and the preview/debug tools in MTM makes it possible to achieve accurate, flexible analytics in modern web environments.

He also noted that a dedicated SPA tracking guide is available for those needing further support.