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 Piwik.

UPDATE: Check out our newly released PiwikTracker iOS SDK to help you track your iOS and OSX apps!

You are maybe familiar with using Piwik 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 Piwik Tracking API.

This tutorial will showcase examples and screenshots of Mobile app tracking using Piwik. The last section of this tutorial explains how to implementat Tracking in your existing app.

Mobile App & Desktop software statistics reports

Using 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

You would also access the power of the Piwik 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:

  1. Install Piwik the Free Software Analytics framework — if you are not already using Piwik
  2. Create a new “Website” in Piwik — set the website name to your App name
  3. Modify your App source code so it sends tracking data to 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 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 Piwik reports.

Use case: Mobile App tracking & reporting

In this section we will showcase how we have used Software Analytics in our Piwik 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 Piwik 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 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. 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

Note: You only need to create the goals in the Piwik 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: 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 Piwik 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 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.

Note: If you want to use Piwik to track a mobile web app running in a web browser, you would probably want to use Javascript Tracking.

Send tracking requests to Piwik 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 “Piwik Tracking” class which will create requests to the 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 )
    • 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: 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 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.

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 Piwik. 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 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.

Conclusion

In this post we have explained how 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 Piwik to track usage data in your next Mobile app or Desktop software. We believe Piwik 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!


Thomas Steur

Thomas is a Software Engineer at Piwik PRO and is a Lead developer for the Piwik Platform. He created and maintains our Piwik Mobile app used by dozens of thousands users every week. Thomas has a passion for making Piwik mobile better and improving the Piwik platform by providing simple APIs and clean code.