How To Use Matomo To Log Version Statistics From An Update Checker

Some of my plugins send queries to my server to check if a later version is available. So I thought about a possibility to log and evaluate the information that is sent along with these queries – most importantly the currently installed plugin version. This would give me an idea about which versions are still in use. Of course, the data doesn’t represent the real distribution of versions since it depends on which plugins query your server how often.

Piwik statistics deployed versions

Retrieving and saving the data didn’t seem to be the problem, but then I needed to process it. You can feed the table into a statistics package, or you can just use a free open source analytics software: Matomo (formerly “Piwik”) can easily be used to collect and analyse data like visits, or even custom events and categories. Usually it works through a Javascript tracking code on a website, but you can also send the events directly from PHP.

In order not to overburden your server with requests and to create a somewhat equal distribution of requests over time, I recommend to cache the retrieved version information in the client software.

In my plugin I also added the option to disable automatic checks in the plugin. Some users might not want the plugin to “call home”. If you want to anonymize the stats, you can also tell Matomo to reduce the accuracy of the location retrieved from the IP address.

Note: This article was written while “Matomo” was still “Piwik”.


  1. First of all, you need of course a working Matomo installation. Log in and click on “Add a new website”. Give it any name you want, for example “Update Checks”. Note down the ID of this website.
  2. Still inMatomo, install and activate the plugin “Custom Dimensions”. Then go to the settings and create a custom dimension for visits (not actions) called “Versions”. Make sure you create it for that new website. Note down the identifier of this dimension – a string like “dimension1”. If you want to track the versions of several packages, you can include their names here: “1st SW Versions”.
  3. Then you will need the file PiwikTracker.php that you find in the downloaded Piwik files (for self-hosting), in the folder “vendor/piwik/piwik-php-tracker/”. It must be includable by the script below. So you possibly have to copy it over to the server where you receive the clients’ requests. Piwik can be installed somewhere else and must only be reachable by HTTP.

Goal “Update Available”

Piwik goal update available

Additionally to reporting all used versions, you can check the reported version against the latest available version and, if the client lags behind, trigger a goal for Piwik. That way you can easily identify requests of clients who should be updating.

In Piwik, create a goal “Update Available” and choose manual triggering, to be triggered only once per visit. Note down the ID of that goal, you will need it for the configuration of the server script.

Alert Users About Available Updates

Finally, you can send back the latest version number to the client. I do it by echoing a JSON-formatted array containing the plugin name, the latest version number, a link to a download and an optional update message.

The Script


Update, February 2018:

The code is now available at BitBucket (GPL license), including a class for WordPress plugins and themes. The documentation there is still a work in progress.


Final Thoughts

As mentioned before, the largest shortcoming is that the statistics will be distorted by irregular frequencies how often users check for updates. You can, however, mitigate this factor by using some kind of cron on the client side so that you try to distribute their requests equally over a longer time span.

Please let me know in the comments if you need more clarification, found a flaw or have further ideas.