Mobile App Analytics: Matomo Tracking

Tracking a new app in Matomo

• In your app, open the /versions/v1/config/app.json file and add the entry matomoTrackingUrl and matomoTrackingId to the context object, i.e.:

app.json

{
  "meta": {...},
  "context": {
    ...
    "matomoTrackingUrl": "",
    "matomoTrackingId": "",
    ...
  }
}

• Set the matomoTrackingUrl to the URL of your Matomo tracking API endpoint, i.e. https://analytics.mobilitysuite.de/matomo.php (make sure the URL is actually leads to the API and not the web GUI, i.e. matomo.php instead of index.php):

app.json

{
  "meta": {...},
  "context": {
    ...
    "matomoTrackingUrl": "https://analytics.mobilitysuite.de/matomo.php",
    "matomoTrackingId": "",
    ...
  }
}

• Next, open your Matomo web GUI and open the admin dashboard by clicking on the gear icon in the top right corner.

• From there, navigate to "Websites > Manage" in the left sidebar to view the list of tracked websites.

note

Do not be confused by the term "Website" here. Matomo refers to every "view", whether it is a page in an actual webapp or screen in an app, as a website.

• Click on "Add a new measurable" and "Website" to configure the tracking settings for your app.

• Enter a name for your app and the URL to your app, which is the URL where your mos. node backend for your app is hosted, e.g. https://example.app.mobilitysuite.de

• Leave the remaining fields unchanged.

If required, change the time zone to your local time zone, e.g. "Germany - Berlin".

• Save your settings.

• After saving, search for the entry you just created in your "Manage Measurables" list and copy the ID.

• Switch back to your app config and set the matomoTrackingId from earlier to the ID you copied in the previous step.

app.json

{
  "meta": {...},
  "context": {
    ...
    "matomoTrackingUrl": "https://analytics.mobilitysuite.de/matomo.php",
    "matomoTrackingId": "12",
    ...
  }
}

• Save your app.json.

Your app is now being tracked in Matomo.

note

It can take several hours until any tracked pages or events appear in your Matomo web GUI. Alternatively, navigate to "Visitors > Real-time" for a less functional but more frequently updated view of your tracking data.

Tracking pages or events in your app

Matomo can track two kinds of items: pages and events.

In general, pages (screens in your app) are limited to client templates in the app config but track some additional data that can not be tracked by events. Events on the other hand allow for a more granular tracking as they can be triggered anywhere in the app, but are more limited in terms of what they track.

Tracking pages

To track a visit to a specific page/screen:

• Open the client template that you want to track and make sure it is being loaded as a node template, i.e. like this:

{
  "type": "showView",
  "params": {
    "target": "view",
    "layout": "myLayout",
    "staticTemplate": "myTemplate",
    "templateIsNode": true  // <-- this is important
  }
}

Node templates must have a top-level content object, containing yet another content object and may also contain an events array and style object like so:

{
  "name": "myTemplate",
  "content": {
    "content": {...},
    "events": [...],
    "style": {...}
  }
}

warning

Tracking of regular ("non-node") client templates (like those used for layout layers) is not possible.

• In your client template, add a top-level string property called trackingKey. The value of this property will be the value displayed in your Matomo dashboard, i.e. if you want to track a page and call it "Settings", then your client template should look like this:

{
  "name": "myTemplate",
  "content": {
    "trackingKey": "Settings",
    "content": {...},
    "events": [...],
    "style": {...}
  }
}

Every time the layout associated with this client template is viewed by a user, a new tracking entry will be crated in your Matomo dashboard.

Grouping/categorizing pages

To group several pages into one and the same category, add a forward slash to your trackingKey.

In the following example we assume that the app has two distinct settings pages that should be tracked individually but still grouped together for ease of use:

{
  "name": "myTemplate1",
  "content": {
    "trackingKey": "Settings/User Settings",
    "content": {...},
    "events": [...],
    "style": {...}
  }
}

{
  "name": "myTemplate2",
  "content": {
    "trackingKey": "Settings/Notification Settings",
    "content": {...},
    "events": [...],
    "style": {...}
  }
}

By naming the trackingKey "Settings", followed by a forward slash and a more detailed name, we can effectively group these two views together in the dashboard. The resulting entry in the dashboard will look similar to this, where "Mitarbeiter" is the parent category and the three child items are the actual pages that are tracked in each client template:

info

Grouping is only available on some pages of the dashboard, such as "Behavior > Entry pages" or "Behavior > Exit pages".

Tracking events

Events allow you to track any action in your app for a more detailed summary in your dashboard. However, they do not support any of the other views in your dashboard, such as "Entry pages".

To track a specific action in your app, go to that action in your config and add the following action to your existing actions by setting the action and label fields to the name you want to use in your dashboard, i.e.:

{
  "type": "trackEvent",
  "params": {
    "action": "Category of my action",
    "label": "Name of my action"
  }
}

Grouping/categorizing events

The action field serves as the group/category that this event should be tracked in.

When viewing events in "Behavior > Events > Event Categories" in your dashboard, all events with the same action will be grouped together in the same category and every child will be named according to the label field.

When viewing events in "Behavior > Events > Event Actions" in your dashboard, the action field will be ignored and all events will simply be shown as a flat list according to their label field.

Likewise, when viewing events in "Behavior > Events > Event Names", all events will be grouped in a generic category and simply displayed as a flat list within it as this feature is currently not supported by the app client.

Manually enable or disable tracking in your app

To programatically disable or enable tracking in your app, add the disableTracking or enableTracking action to your app. This may be useful to provide your users with an opt-in or opt-out feature:

{
  "type": "container",
  "name": "disableTrackingButton",
  "constraints": [...],
  "actions": [
    {
      "type": "disableTracking"
    }
  ]
},
{
  "type": "container",
  "name": "enableTrackingButton",
  "constraints": [...],
  "actions": [
    {
      "type": "enableTracking"
    }
  ]
}

Viewing tracking information in your dashboard

To view tracked pages in your Matomo dashboard, navigate to one of the sub-items in "Dashboard", "Visitors" or "Behavior > Pages (or Entry/Exit Pages)" in the left sidebar.

To view tracked events in your dashboard, navigate to "Behavior > Events" and click on "Event Categories" or "Event Actions" in the left navigation pane.

The "Acquisition", "Goals" and "Marketplace" entries are not relevant when tracking an app and are only useful for tracking websites.

Creating tracking reports

• Navigate to the settings in your Matomo dashboard by clicking on the gear icon near the top right corner and click on "Personal > Email Reports".

• Click on "Create and schedule a report".

• Enter an optional description and select your email schedule, report period (timeframe of tracked pages and events to be included in the report), report time, etc.

Fetching datasets via the Matomo API

If the built-in tracking reports feature is too limited or the way the data is presented is not to your liking, you may try fetching the data directly from Matomo's reports API:

• Go to "Settings (gear icon)" > "Personal" > "Security" > scroll down to "Auth tokens".

• Create a new auth token by entering your password and a description for the token.

• Copy the generated token and save it to a safe location (i.e. your key store/password manager).

To fetch which tracked pages have been visited by users, request the data as follows:

GET https://analytics.mobilitysuite.de/?module=API&format=json&method=Actions.getPageTitles&idSite=123&period=range&date=2024-01-01,now&showColumns=nb_visits,nb_uniq_visitors&filter_limit=10&token_auth=1234567890abcdefghijklmnopqrstuv

To fetch which tracked events have been triggered by users, request the data as follows:

GET https://analytics.mobilitysuite.de/?module=API&format=json&method=Events.getCategory&secondaryDimension=eventAction&flat=1&idSite=123&period=range&date=2024-01-01,now&token_auth=1234567890abcdefghijklmnopqrstuv

The params in the above two requests have the following meaning:

• module is required and format should be left at json for most use cases. When format is omitted, XML will be used by default.
• idSite is the id (matomoTrackingId) of the site/app in your Matomo dashboard.
• filter_limit is used to limit the dataset to a maximum number of entries.
• token_auth is the token you generated earlier (the token used in the above exmaples does not actually exist and is only used for demonstration purposes).
• method determines which dataset is fetched (e.g. Actions.getPageTitles for pages by their page title, Events.getCategory for events by their category, etc.)
• period and date are used to limit the dataset to a specific range.
• showColumns can be used to display only specific fields in your dataset. When omitted, all fields will be shown instead.

For events you may also use these additional params:

• secondaryDimension is only useful for events and can be used to select a specifiy type of event, equivalent to "Event Categories", "Event Actions" and "Event Names" in the dashboard.
• flat is only useful for events and can be used to expand the segment field into separate Events_EventCategory and Events_EventAction fields.

For more details and other datasets that can be fetched via the reports API, check the official matomo documentation.

User and permissions management

Users

To add a new user to your Matomo installation, proceed as follows:

• Navigate to the settings page in your Matomo dashboard by clicking on the gear icon near the top right corner.

• Click on "System => Users" in the left side navigation pane.

• Add a new user by clicking on "Invite a new user" and enter their Username (i.e. their real name) and email address, as well as the app they should have access to, in this case "First website permission".

Alternatively to give an existing user access to one of your apps.

• Navigate to "System > Users" in the left side navigation pane.

• Click on the "Role for" select box and pick the app that you want to make available to the user.

• Then select their permission level (typically "view") in the dropdown below.

Permissions

To change a user's permissions, proceed as follows:

• Navigate to the settings page in your Matomo dashboard by clicking on the gear icon near the top right corner.

• Click on "System > Users" in the left side navigation pane.

• Use the "User search" text field to search for the user you want to modify and click on the "Edit" icon in the "Actions" column.

• Change the user's basic information or navigate to the "Permissions" entry on the left and search for a specific app in the search field (called "Filter by website" here)

• Change the "Role" for that specific user (typically "view"), or modify the user's capabilities such as access to certain parts of the Matomo dashboard like the Tag Manager.