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:
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 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.
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:
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.
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:
/matomo.php. This is due to the fact that the open source clients used by Prenly have this limitation.The following configuration parameters are set up in Prenly Workspace.
The site ID configured in the Matomo server, as an integer.
Example: 5
The URL that tracking data will be sent to, ending with matomo.php.
Example: https://my.site.com/matomo.php
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.
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.
| Action dimension id | Request parameter name | Prenly event attribute | Used in events |
|---|---|---|---|
| 1 | dimension1 | application_slug | - |
| 2 | dimension2 | title_slug | replica_page_open, replica_pages_view, article_open, article_view, publication_open, favorite_title_add, favorite_title_remove, replica_box_link_click, replica_box_link_view, title_open, article_audio_start, article_audio_stop |
| 3 | dimension3 | title_uid | replica_page_open, replica_pages_view, article_open, article_view, publication_open, favorite_title_add, favorite_title_remove, replica_box_link_click, replica_box_link_view, title_open, article_audio_start, article_audio_stop |
| 4 | dimension4 | publication_slug | replica_page_open, replica_pages_view, article_open, article_view, publication_open, replica_box_link_click, replica_box_link_view, article_audio_start, article_audio_stop |
| 5 | dimension5 | publication_uid | replica_page_open, replica_pages_view, article_open, article_view, publication_open, replica_box_link_click, replica_box_link_view, article_audio_start, article_audio_stop |
| 6 | dimension6 | publication_date | replica_page_open, replica_pages_view, article_open, article_view, publication_open, replica_box_link_click, replica_box_link_view, podcast_episode_start, podcast_episode_stop, article_audio_start, article_audio_stop |
| 7 | dimension7 | page_number | replica_page_open, replica_box_link_click, replica_box_link_view |
| 8 | dimension8 | part_slug | replica_page_open |
| 9 | dimension9 | article_slug | article_open, article_view, article_audio_start, article_audio_stop |
| 10 | dimension10 | article_uid | article_open, article_view, article_audio_start, article_audio_stop |
| 11 | dimension11 | article_name | article_open, article_view, article_audio_start, article_audio_stop |
| 12 | dimension12 | article_external_id | article_open, article_view |
| 13 | dimension13 | section_slug | article_open, article_view |
| 14 | dimension14 | external_url (deprecated) | |
| 14 | dimension14 | destination_url | replica_box_link_click, replica_box_link_view, banner_click |
| 15 | dimension15 | push_notifications_enabled | prenly_app_open |
| 16 | dimension16 | push_notification_uid | prenly_push_notification_open |
| 17 | dimension17 | push_notification_sent_at | prenly_push_notification_open |
| 18 | dimension18 | message_title | prenly_push_notification_open |
| 19 | dimension19 | message_body | prenly_push_notification_open |
| 20 | dimension20 | customer_number | all (if available) |
| 21 | dimension21 | consent_analytical (if known - sent as "0" or "1") |
all (for certain CMP:s) |
| 22 | dimension22 | consent_functional (if known - sent as "0" or "1") |
all (for certain CMP:s) |
| 23 | dimension23 | consent_marketing (if known - sent as "0" or "1") |
all (for certain CMP:s) |
| 24 | dimension24 | banner_type | banner_click |
| 25 | dimension25 | external_link_id | replica_box_link_click, replica_box_link_view |
| 26 | dimension26 | consent_services | all (for certain CMP:s) |
| 27 | dimension27 | channel_title | podcast_episode_start, podcast_episode_stop |
| 28 | dimension28 | channel_slug | podcast_episode_start, podcast_episode_stop |
| 29 | dimension29 | episode_title | podcast_episode_start, podcast_episode_stop |
| 30 | dimension30 | episode_entity_id | podcast_episode_start, podcast_episode_stop |
| 31 | dimension31 | time_spent | article_view, replica_pages_view |
| 32 | dimension32 | playback_position | podcast_episode_start, podcast_episode_stop, article_audio_start, article_audio_stop, external_audio_start, external_audio_stop |
| 33 | dimension33 | page_numbers | article_view, replica_pages_view |
| 34 | dimension34 | audio_duration | podcast_episode_start, podcast_episode_stop, article_audio_start, article_audio_stop, external_audio_start, external_audio_stop |
| 35 | dimension35 | played_duration | podcast_episode_stop, article_audio_stop, external_audio_stop (will also be added as Matomo event value to these events) |
| 36 | dimension36 | audio_entity_id | external_audio_start, external_audio_stop |
| 37 | dimension37 | audio_title | external_audio_start, external_audio_stop |
| 38 | dimension38 | limited_access | publication_open |
| 39 | dimension39 | article_uids | replica_pages_view |
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):
| Parameter | Purpose | Information |
|---|---|---|
| rec | Whether to record event | Always set to true (sent as "1" ) |
| siteid | The tracking server site ID | As configured in Prenly Workspace |
| e_c | Event category | Always set to "prenly-event" |
| e_a | Event action | Always set to "interaction" |
| e_n | Event name | The Prenly event name, for example "article_open" |
| e_v | Event value | For metric values in events that.can be aggregated, e.g. “played_duration” and “time_spent” |
| res | Screen resolution | For example "1280x1024" |
| uid | Unique user id if applicable | The user_id value from the user information contextual data |
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.