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 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.
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
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']);
_paq.push(['trackPageView']);
});
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']);
_paq.push(['trackPageView']);
Note: we recommend you use Custom Dimensions instead of Custom Variables as they will be deprecated in the future.
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]);
_paq.push(['trackPageView']);
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]);
_paq.push(['trackPageView']);
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).
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.
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:
_paq.push(['enableLinkTracking']);
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.
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.
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']);
_paq.push(['trackPageView']);
// 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]);
_paq.push(['enableLinkTracking']);
});
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:
{event: 'mtm.PageView'} by calling the following line in JavaScript: window._mtm.push({'event': 'mtm.PageView'});.
window._mtm.push({'event': 'DOMReady'});) or when you use the 'Window Loaded Trigger' (call _mtm.push({'event': 'WindowLoad'});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.