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). Not using Matomo yet? Try our live demo and start your 21-day free trial today – no credit card required.
UPDATE: Check out our iOS / Swift SDK and our Android SDK to help you track your iOS and OSX apps!
You are maybe familiar with using Matomo and track visits using the Javascript code. In many cases however, using Javascript is not an option. Luckily you can also track user interactions from non Javascript devices using the Matomo Tracking API.
This tutorial will showcase examples and screenshots of Mobile app tracking using Matomo. The last section of this tutorial explains how to implementat Tracking in your existing app.
Mobile App & Desktop software statistics reports
Using Matomo 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
You would also access the power of the Matomo platform: Automatic Email reports (PDF, HTML), Analytics API, Historical analysis and much more.
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 the Free Software Analytics framework — if you are not already using Matomo
- Create a new « Website » in Matomo — set the website name to your App name
- Modify your App source code so it sends tracking data to Matomo (clicks, settings, errors, etc.) using the Mobile SDKs (iOS, or Android)
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 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
In Matomo Mobile, we decided to differentiate three types of pageviews: Window, Event and Exceptions.
- 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’. - Event
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 Dimensions
Custom Dimensions are extremely powerful as they let you track any custom name and value for your visitor or page views.
- In a Custom Dimension 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 Dimensions with scope ‘Action’ 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 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
Note: You only need to create the goals in the Matomo interface, tracking goals does not require code changes in your App tracking source code.
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: 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 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.
Note: If you want to use Matomo to track a mobile web app running in a web browser, you would probably want to use Javascript Tracking.
Send tracking requests to Matomo from your Android or iOS Mobile app
Use the official Matomo SDK for iOS / Swift or the Matomo SDK for Android to help you track your iOS and OSX and Android apps.
Send tracking requests to Matomo from your 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, C# 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 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 )
- etc.
- 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)
- etc.
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 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, 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.
In our Mobile App, we create an anonymous unique user id for each user. Here is an example of an ID generation in Javascript:
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 use « Opt-in » and track all usage by default, we highly recommend to update your App Privacy Policyto mention the fact that users will be tracked using Matomo. We highly recommend to have a setting that will let users disable this tracking if they wish.
- 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 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.
Conclusion
In this post we have explained how Matomo 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 to track usage data in your next Mobile app or Desktop software. Matomo is a reliable and effective Open Source Software Analytics Platform and we are looking forward to seeing how this technique helps you!
Check our live demo and start your 21-day free trial now – no credit card required.
For any question or feedback, please leave a comment here or ask in the forums.
Happy Software & Mobile Analytics!
