The Matomo JS tracker supports tracking users while they are offline and executing the tracking requests as soon as they come online. This can be for example useful in progressive web apps (PWA). To make use of this feature follow below steps.

Step 1. Register service worker

If you have not registered a service worker yet, create a JS file and register your service worker like this:

if ('serviceWorker' in navigator) {
    window.addEventListener('load', function() {
       // adjust `your-service-worker.js` to match the file name of your worker
        navigator.serviceWorker.register('https://static.matomo.org/your-service-worker.js'); 
    });
}

Step 2. Initialise offline tracking

Within your service worker add this code:

// replace `https://your.matomo.domain` with the domain and path to your Matomo installation
self.importScripts('https://your.matomo.domain/offline-service-worker.js');
matomoAnalytics.initialize();

The method initialize supports currently these options:

  • queueLimit: Defaults to 50 and defines how many requests will be queued max while a user is offline. If more requests than the configured limit are queued, the oldest requests will be removed.
  • timeLimit: Defaults to 86400 seconds (1 day) and specifies after how many seconds the tracking requests should be disregarded if the user does not come online. This is set to 1 day because the Matomo tracker API requires authentication should you try to record a tracking request for more than a day in the past. If you want to keep the requests for more than one day, you will need to change this setting and also configure the time after which Matomo tracking requests require authentication.

Example:

matomoAnalytics.initialize({queueLimit: 100, timeLimit: 86400*2});

Known limitations

So far only our standard tracking endpoints are supported: matomo.js, piwik.js, matomo.php and piwik.php. If you are using a custom path like tracker.js and tracker.php this is not supported yet.

This feature requires Matomo 4. It is currently available as part of our latest Matomo 4 beta release see our FAQ on how to update your Matomo to the latest beta release.

Running into any issues?

If you run into any issues using this feature please let us know in our GitHub issues tracker.