How do I set up Matomo offline tracking?

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. (Note: if you are instead looking for « How to track offline sales? » then learn how to track offline conversions (from a physical shop or event).)

Step 1. Create a file for the service worker

If you don’t have a service worker yet, then you need to create a file for your service worker in the root directory of your website. In below example we assume the file is called service-worker.js.

Step 2. Register service worker

If you have not registered a service worker yet, register your service worker like this in your website:

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

Every page where you want to utilise offline tracking needs to include this snippet.

Step 3. Initialise offline tracking

Within your service worker (for example in your service-worker.js) 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.

We need your feedback

Running into any issues?

We’d love to hear your feedback if this feature is working for you or not. Simply leave a comment on the offline tracking issue if this is working for you.

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

Are you a service worker or IndexedDB pro?

We’d love if you could help us review our implementation. You can check out the code in the offline tracking pull request. We appreciate any feedback to help us improve this feature!