This post is aimed at Mobile Apps developers and Software developers (Desktop apps) who wish to implement Usage Tracking & Analytics of their apps using the leading Free Web Analytics platform Matomo (Piwik).
UPDATE: Check out our newly released PiwikTracker iOS SDK to help you track your iOS and OSX apps!
This tutorial will showcase examples and screenshots of Mobile app tracking using Matomo (Piwik). The last section of this tutorial explains how to implementat Tracking in your existing app.
Mobile App & Desktop software statistics reports
Using Matomo (Piwik) to track your app usage would give interesting statistics usage such as:
- number of active users (per day, week, month, …) of my mobile or desktop app,
- how long users spend in the app,
- track which icons, buttons are clicked (or any other custom event),
- record device info, operating system,
- reports on any Custom Variables you that are relevant to your app (see examples below),
- how often is the app opened? When and how long is the app opened?
- number of new users, active users, total users,
- record errors or exception thrown
How do I get Free Software Analytics and Mobile App tracking?
To track usage data in your existing Mobile app or Desktop app, you will need to:
- Install Matomo (Piwik) the Free Software Analytics framework — if you are not already using Matomo
- Create a new “Website” in Matomo (Piwik) — set the website name to your App name
- Modify your App source code so it sends tracking data to Matomo (Piwik) (clicks, settings, errors, etc.) using the Tracking API
Implementing tracking in an App requires technical knowledge and will take a minimum of 2 hours to implement and can take up to 2 days for a complex software. Implementation depends on how much data should be tracked and how easy it is to add the tracking calls in your software source code.
Once you deploy your app or software with Matomo (Piwik) tracking, statistics about your software will be available in Real time. You will then access all reports such as “Top Pages”, “Goal conversions”, “Locations & Provider” and other standard Matomo reports.
Use case: Mobile App tracking & reporting
In this section we will showcase how we have used Software Analytics in our Matomo Mobile App to provide relevant and useful reports on our Mobile App usage. The last section of this tutorial will explain implementation steps and technical details.
Example tracking clicks and events
- Window change
Everytime the user opens a new window, we track a pageview with the url path starting with ‘/window‘. For example ‘/window/statistics/show‘ which means the user opened the statistics window. We also generate an appropriate custom title, for example ‘Statistics Show’.
Events are actions within a window, eg. user selects another date or changes a setting. Each event is tracked with url path starting with ‘/event‘. For example ‘/event/settings/change-language‘ and the title ‘Settings Change Language’.
- Error or exception
If an error occurs or something unexpected happens, we track the occurred exception starting with ‘/exception‘.
For example ‘/exception/TypeError/filename/line‘. This helps us identify issues users experience.
Example tracking Custom Variables
Custom Variables are extremely powerful as they let you track any custom name and value for your visitor or page views.
- In a Custom Variable with scope ‘Visit’, we track for example the current used Mobile App Version, the operating system including the exact version number, the used locale (language code) and the number of accounts each user created.
- In Custom Variables with scope ‘Page’ we track window related variables. For example in the statistics window, we track which report the user is currently viewing and which period is being used.
Example: tracking Goals in your app
Tracking Goals is a great way to track and measure your business objectives. Matomo (Piwik) provides many reports for each configured Goal. In our Mobile App, we created Goals with the following definitions (see screenshot):
- Create an account
Visit a given URL (page or group of pages), Pattern contains: /account/create/success
- Click on Contact/Feedback
Visit a given URL (page or group of pages), Pattern contains: /help/feedback
- Click on Visit settings
Visit a given URL (page or group of pages), Pattern contains: /settings/index
Goal reports will show the conversions, conversion rate and revenue per visit for each Country, Custom Variable, etc. You can also easily visualize how popular a specific part of your app is over time by analyzing the evolution graphs at the top of the Goal report.
Example: tracking Visit count
If you would like to populate the report “Visitors > Engagement > Visits by visit number”, you can manually set the REST API parameter ‘_idvc’. We store this value in the user session on the phone. The visit counter is incremented if the user starts the app again but not if the user resumes the application from background.
Example: Opt-in tracking UI
Our official Matomo Mobile application offers an opt-in feature to let users send us anonymously their clicks and usage data. Users can enable and disable the opt-in usage tracking mechanism at any time. When the users are not opt-in (which is the default) no data is sent to the Matomo (Piwik) server at all.
Example: Visitor Log in a Mobile Analytics use case
The Visitor Log will let you easily visualize the full set of actions for each visitor on your website. The Visitor Log shows all custom variables set to the visit, Converted goals, all Pageviews/events during the visit. It can even be used for troubleshooting a particular user of your app or software.
How do I implement tracking in my app?
In this section we will describe at a high level how to implement the source code changes required to make Tracking your app possible.
Send tracking requests to Matomo from your mobile app / desktop software
If you use the programming languages PHP, Java or Python, it will be easy to implement tracking in your app since there is already a Tracking API client in these languages: see doc PHP & Java tracking clients.
If you use another programming language (python, ruby, etc.), you will have to enhance your source code by creating a “Matomo Tracking” class which will create requests to the Matomo (Piwik) Tracking API (link opens the Tracking REST API reference doc).
This new class in your project will typically allow to set attributes (url, idsite, action_name, etc.) and then trigger the HTTP request to /piwik.php (the tracking API endpoint). Other areas of your code (Window manager, Click manager, etc.) would then instantiate an instance of this class, set the parameters, and then trigger the request.
This class would typically have a few functions such as:
- functions to set attributes:
- setUrl( url )
- setUserAgent( userAgent )
- setVisitorId ( id )
- functions to use these attributes to build a HTTP request to record the visit/event
- trackPageView ( customPageTitle ) — triggers the HTTP request to /piwik.php using your favorite programming language HTTP library / function.
- trackGoal ( idGoal)
Creating such a class is just a suggestion (there might be better ways to do it in your environment). For inspiration, we recommend to check out the PiwikTracker PHP client documentation.
To set the parameters correctly, please head over to the Tracking API documentation: Matomo (Piwik) Tracking API Reference
Assign a custom unique id to each user
To make sure that all requests from a given user are sent to the right visitor in Matomo (Piwik), it is highly recommended to set a unique ID to the user using your app. The parameter is called _id and must be hexadecimal string with a length of 16 characters.
var uuid = os_name() + unique_id_of_device();
uuid += phone_model() + random_unique_id();
uuid = md5(uuid).slice(0, 16);
Other important notes
- For performance reasons, it is very important that you send the Tracking requests only after all the content is loaded in your application. User experience and speed is always more important than usage tracking!
- If you do not provide such a setting to disable User Tracking, your app wouldn’t follow industry best practises and might be considered a spyware.
- In a Mobile or Desktop app, there is not really a notion of Page URL. Because Matomo (Piwik) Tracking API requires a URL, we recommend to create fake (but still useful!) URLs such as: http://myapp/menu/about-us/newsletter-add
- It is important to choose your URLs wisely, with useful names (the button being clicked, the menu label, etc.). A relevant naming scheme will make the data analysis much more useful. It will also help you to easily create Goals using URL matching.
- To record more information than the URL and Page Title, you could also use Custom Variables.
In this post we have explained how Matomo (Piwik) can be used to track Mobile App user interactions or desktop software usage. We have highlighted a few examples of useful usage statistics using the example of our own mobile application usage data. While implementing Mobile App Analytics might take a few hours of coding work, the value of aggregated usage data presented in a clean User Interface (Piwik!) is certainly worth it.
We hope that you will consider using Matomo (Piwik) to track usage data in your next Mobile app or Desktop software. We believe Matomo is now a reliable and effective Open Source Software Analytics Platform and we are looking forward to seeing how this technique helps you!
For any question or feedback, please leave a comment here or ask in the forums.
Happy Software & Mobile Analytics!