Single-Page Application/Progressive Web App Tracking

Single-page websites and Progressive Web Apps have become a standard over the last years. Getting the tracking of such websites and apps right is crucial to your success as you need to ensure the measured data is meaningful and correct.

If available, consider using an existing integration for your framework

If you're using a popular framework such as Angular, Angular JS, Vue.js, React Native, etc. then we recommend to first check if an integration may be available for your framework: see all available integrations for Matomo.

Embedding the Tracking Code

First you need to embed your JavaScript tracking code into your single-page website or web application as usual. To do this go to “Administration” in the top right in your Matomo instance, click on “Tracking Code” and adjust the tracking code to your needs. You can find more information in our JavaScript Tracking Client documentation

Tracking a New Page View

The challenge begins when you need to track a new page view. A single-page application is different from a usual website as there is no regular new page load and Matomo cannot detect automatically when a new page is viewed. This means you need to let Matomo know whenever the URL and the page title changes. You can do this using the methods setCustomUrl and setDocumentTitle like this:

window.addEventListener('hashchange', function() {
        _paq.push(['setCustomUrl', '/' + window.location.hash.substr(1)]);
        _paq.push(['setDocumentTitle', 'My New Title']);

Resetting previously set custom variables

If you have set any Custom Variables in scope “page”, you need to make sure to delete these custom variables again as they would be attributed to the new page view as well otherwise:

_paq.push(['deleteCustomVariables', 'page']);

Note: we recommend you use Custom Dimensions instead of Custom Variables as they will be deprecated in the future.

Resetting previously set custom dimensions

Similar to Custom Variables, you also need to unset Custom Dimensions when changing the page as they would otherwise be tracked again.

_paq.push(['deleteCustomDimension', 1]);

Updating the referrer

Depending on whether you want to track the previous page as a referrer for the new page view, you should update the referrer URL by setting it to the previous page URL:

_paq.push(['setReferrerUrl', previousPageUrl]);

Making Matomo Aware of New Content

When you show a new page, your single-page DOM might change as well. For example, you might replace parts of your page with new content that you loaded from your server via Ajax. This means you need to instruct Matomo to scan the DOM for new content. We'll now go over various content types (Videos & Audio, Forms, Links and Downloads, Content tracking).

Video and Audio tracking

If you use the Media Analytics feature to track your videos and audios, whenever a new page is displayed you need to call the following method:

_paq.push(['MediaAnalytics::scanForMedia', documentOrElement]);

When you don’t pass any parameter, it will scan the entire DOM for new media. Alternatively, you can pass an element to scan only a certain area of your website or app for new media.

Form tracking

If you use the Form Analytics feature to measure the performance of your online forms, whenever a new page is displayed you need to call the following method:

_paq.push(['FormAnalytics::scanForForms', documentOrElement]);

Where documentOrElement points either to document to re-scan the entire DOM (the default when no parameter is set) or you can pass an element to restrict the re-scan to a specific area.

Supposing that you use the link tracking feature to measure outlinks and downloads, Matomo needs to re-scan the entire DOM for newly added links whenever your DOM changes. To make sure Matomo will track such links, call this method:


Content tracking

If you use the Content Tracking feature, whenever a new page is displayed and some parts of your DOM changes, you need to call this method :

_paq.push(['trackContentImpressionsWithinNode', documentOrElement]);

Where documentOrElement points either to document or an element similar to the other methods. Matomo will then scan the page for newly added content blocks.

Heatmap & Session Recording

To support single-page websites and web applications out of the box, Heatmap & Session Recording will automatically detect a new page view when you call the trackPageView method. This applies if you call trackPageView several times without an actual page reload. Matomo will after each call of trackPageView stop the recording of any activities and re-evaluate based on the new URL whether if it should record activities for the new page or not.

If you have a single-page website and you use trackPageView for any other purposes than an actual page view, it is recommended to disable the default behaviour using this method and let Heatmap & Session Recording explicitly know when there is a new page view by calling the two methods disableAutoDetectNewPageView and setNewPageView.

If you're setting a Custom URL in the single-page website, you may need to use the matchTrackerUrl() in order to allow the Matomo tracker to correctly trigger Heatmaps and Session Recordings.

Learn more in the JS Tracker API reference for Heatmaps & Session Recording.

Measuring Single-Page Apps: Complete Example

In this example we show how everything works together assuming you want to track a new page whenever a hash changes:

var currentUrl = location.href;
window.addEventListener('hashchange', function() {
    _paq.push(['setReferrerUrl', currentUrl]);
     currentUrl = '/' + window.location.hash.substr(1);
    _paq.push(['setCustomUrl', currentUrl]);
    _paq.push(['setDocumentTitle', 'My New Title']);

    // remove all previously assigned custom variables, requires Matomo (formerly Piwik) 3.0.2
    _paq.push(['deleteCustomVariables', 'page']); 

    // make Matomo aware of newly added content
    var content = document.getElementById('content');
    _paq.push(['MediaAnalytics::scanForMedia', content]);
    _paq.push(['FormAnalytics::scanForForms', content]);
    _paq.push(['trackContentImpressionsWithinNode', content]);

Using Matomo Tag Manager to track Single Page Application

If you're using Tag Manager to implement your Matomo Analytics Tracking, then in your Single Page Application, whenever there is a new page loaded in your app you will need your Matomo Tag to be triggered for the Page view to be tracked.

To trigger your Matomo tag (which calls trackPageView), you can either:

  1. use the "History change" trigger which would work in most cases,
  2. or in your Single Page App, if you are using the 'Pageview Trigger' to trigger a Pageview, you can trigger a Tag Manager Event {event: 'mtm.PageView'} by calling the following line in JavaScript: window._mtm.push({'event': 'mtm.PageView'});.
    • This would also work similarly when you use instead the 'DOM Ready Trigger' (call window._mtm.push({'event': 'DOMReady'});) or when you use the 'Window Loaded Trigger' (call _mtm.push({'event': 'WindowLoad'});

Offline Tracking

If your web application requires offline tracking, please refer to the Matomo offline tracking guide.


If you have any questions or need help, please get in touch with our support team or for free support: ask on the forum.