DHT

[Solved]: Use Piwik Pro Progressive Web App analytics in a vanilla html and javascript project

by Dylan Thomas
Published:
Reading time:
3 min

Background

I was packaging up a website as a PWA (progressive web application) so that it could be used offline at a conference, and I wanted to have some analytics collected while offline.

After a lot of searching, I came across Piwik Pro, a capable analytics package that specifically included capabilities for offline analytics tracking. Perfect!

However, their code assumes that you are building your project using a framework with a packaging-based workflow. My project was simple, vanilla html and javascript.

I looked everywhere to see how I could use Piwik Pro analytics for a PWA that wasn’t built with a framework and I didn’t find anything useful. (I did, however, find 2 other people over the past 3 years trying to do the same thing and not receiving any help).

I finally figured it out, so here is what I did that worked for me, hoping that it might work for you.

Official Documentation

Piwik Pro Developer Documentation > Progressive web applications integration (PWA)

Limitations/Future Updates

While the Piwik PWA integration has 3 components, this solution only covers the main analytics handled by the service worker.

This solution does not enable the internet connection and install tracking features. Those need to be handled by the main application’s javascript due to the context separation between the main browser window and the service worker.

I am working on a similar approach to enable these features.

Overview of solution

Since our project is not using a packaged-based framework, we will use a packager solely to convert the Piwik package into a javascript file we can import into our service worker (bundle.js).

Steps

  1. Install modules
  2. Create a js file (piwik.js) that imports @piwikpro/pwa-piwik-pro
  3. Configure Rollup
  4. Use Rollup to build javascript bundle (piwik_bundle.js)
  5. Import javascript bundle into service worker

Install modules

In your project folder, run the following commands:

npm install @piwikpro/pwa-piwik-pro

Installs the Piwik Pro PWA Integration module

npm install -g rollup

Installs Rollup as a global command, which will let us create piwik_bundle.js.

npm install @rollup/plugin-node-resolve

Allows Rollup how to find the node modules it needs

npm install @rollup/plugin-replace

Allow us to replace some dynamic node environmental variables in bundle.js with static values that will work in the browser.

Create a js file (piwik.js) importing Piwik

In piwik.js , put the following:

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

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

Replace the containerURL and containerId with the values from your account.

Configure Rollup

Create a rollup.config.mjs in your project directory with the following:

import resolve from '@rollup/plugin-node-resolve';
import replace from '@rollup/plugin-replace';

export default {
	input: 'piwik.js',
	output: {
		file: 'piwik_bundle.js',
		format: 'iife',
		sourcemap: true
	},
	plugins: [
		resolve(),
        replace({
			'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'),
			preventAssignment: true
		}),
	]
};

Use Rollup to build

In your project folder, run:

rollup -c

This should process everything you need into piwik_bundle.js.

Import build into service worker

Add the following into your service-worker js file:

// Import Piwik Pro Scripts
importScripts('piwik_bundle.js')

Testing

The module should now be working as designed.

The best way to see that it is working is to use the Tracker Debugger which shows you what the tracker is doing in real-time.