Progressive web applications integration (PWA)

When building an application that works offline, it's crucial to understand how users interact with your app without connectivity to optimize their experience.

Analytics providers like Piwik PRO typically require a network connection to send data to their servers. If connectivity is unavailable, these requests will fail, and the interactions will be missing from your reports, as if they never happened.

Our integration with Progressive web applications (PWA) addresses this issue for Piwik PRO users by using the service worker’s ability to handle failed requests.

Piwik PRO receives data via HTTP requests, so a service worker script can add a fetch handler to detect failed requests sent to Analytics. It stores these requests in IndexedDB and retries them once connectivity is restored.

The PWA module for Piwik PRO handles this process. It adds fetch handlers to cache the ppms.js and container scripts for offline use. Additionally, when retrying failed requests, the module automatically sets or updates the cdt (current date-time) in the request payload, ensuring that timestamps in Piwik PRO reflect the time of the original user interaction.

Enable the Piwik PRO module for progressive web applications

To enable data collection from your PWA with Piwik PRO Analytics, call the initialize() method in your service worker:

import PiwikPro from '@piwikpro/pwa-piwik-pro';

PiwikPro.initialize({
    containerURL: 'example.com',
    containerId: '12345678-1234-1234-1234-1234567890ab'
});

This setup is all you need to queue and retry failed requests to Piwik PRO, and it’s the simplest way to get Piwik PRO working offline.

However, using only the code above means that retried requests will be indistinguishable from those that succeed on the first attempt. While you'll collect all interaction data from offline users, you won’t be able to identify which interactions occurred while the user was offline.

To address this, you can use one of the optional methods described below.

Enable automatic tracking of the status of the user’s internet connection

To differentiate between retried and non-retried requests, you can enable automatic tracing of the internet connection status. This solution will generate a custom event with information about the connection status whenever the internet is lost.

In your application, include the default PiwikPro object in the top-level module, such as index.js.

import PiwikPro from '@piwikpro/pwa-piwik-pro';

PiwikPro.enableInternetConnectionTracking();

Enable automatic tracking of the app installation event

If you want to track when your customers install the application as a custom event, you can do so using the following method:

import PiwikPro from '@piwikpro/pwa-piwik-pro';

PiwikPro.enableInstallTracking();