Matomo Analytics

Introduction

Matomo (formerly Piwik) is an open-source analytics tool that provides comprehensive insights into website and application usage. It collects and stores data, and provides a web interface to view real-time data and create reports. Visit https://matomo.org for more information.

This integration can be used in multiple ways:

• subscribe to Matomo Cloud, which includes hosting and support
• install Matomo on your own server for full control over your data
• build your own endpoint that parses event data, which allows you to store and manage the data exactly how you want

Implementation details

The Prenly Reader clients will send statistical data to the Matomo server tracking api endpoint, according to the official documentation of the Matomo tracking api, using:

• the official Matomo's official JavaScript SDK from the Prenly web reader.
• the open source SDK:s for Android  och iOS from the Prenly native app readers. This requires the SDK:s to be added to the native app's program code, which implies that new app versions must be compiled and released before the integration will start working.

The current implementation supports exporting events, but not "page views", since the Prenly Reader does not rely on traditional page-based navigation.

Prenly do not support Matomo Tag Manager as it is primarily a solution for web environments, and therefore not directly applicable to Prenly's native clients.

Setup

Setting up a Matomo server

Using a Matomo server

The normal Matomo setup requires the opens source Matomo server software to be installed on-premise or via an externally hosted service, offered by matomo.org or by other companies. The server software will expose an api that collects statistical data, and a web tool that lets you view and analyze the data.

In the web tool, you need to:

• create a "site" that corresponds to the Prenly application, which will result in a "site ID"
• manually add "custom dimensions" (metadata for various events) that Prenly will send

When technically dealing with metadata/custom dimensions in Matomo, each dimension is referred to as a plain integer number, as it is saved in Matomo's database.

When adding custom dimensions via the web tool, they are created in numerical order (1, 2, 3, …). Since Prenly will send dimensions according to the list below, it is important to create the custom dimensions in the correct order. 

Implementing a custom tracking endpoint

By studying the specification of the Matomo tracking api, it is possible to implement your own api endpoint that collects the metric data sent from the Prenly Reader applications.

This is useful if you want to store metric data in your own system and/or in your own format. The Matomo tracking api is simple, so such an endpoint should be fairly simple to implement.

Note the following:

• There should be only one endpoint, and it must respond to both the GET (single event) and POST (a batch of events) methods as described in the docs.
• The URL to the endpoint must end with /matomo.php. This is due to the fact that the open source clients used by Prenly have this limitation.
• The custom dimensions sent by Prenly will be named according to the list below.

Configure the integration in PWS

The following configuration parameters are set up in Prenly Workspace.

Site ID

The site ID configured in the Matomo server, as an integer.

Example: 5 

Tracking api URL

The URL that tracking data will be sent to, ending with matomo.php.

Example: https://my.site.com/matomo.php 

Data transformation

General

Due to technical limitations, all properties are sent to Matomo as strings.

Event attributes that are booleans are sent as "0" for false and "1" for true.

Event attributes

In Matomo,  custom dimensions are used to represent event-specific attributes. In the Matomo server software, these custom dimensions must be set up by an administrator in your Matomo server's web interface. Unfortunately, Matomo do not offer a way to name or identify these dimensions, instead they will get a number representing their ID in the Matomo server's database.

Prenly will send custom dimensions according to the table below. For the ID:s to match the table below, you should add the custom dimensions in the correct order.

Contextual data

Contextual data are sent as parameters as documented in Matomo's tracking api.

The open source SDK:s used in the Prenly Reader applications, implements data tracking slightly differently. This diversity leads to variations in the data sent from each client type to the Matomo server.

These parameters are confirmed being sent from all platforms (web, Android, iOS):

Other parameters can not be guaranteed to be sent.

Note that we specifically do not override the user agent using the “ui” parameter. Still some platforms may send it, but you should not trust it. Instead, you must check the User-Agent HTTP header to be able do determine the user agent and the platform.