How to use Matomo's Server Side Tracking

How to use Matomo's Server Side Tracking

Published at: 08/26/2022
Updated at: 08/29/2022

Use Server Side Tracking on Matomo to enhance your analytics

With Matomo we can enable the server side analytics tracking and get a more precise and enhanced monitoring of your website's traffic.

Server-Side Tracking vs Client-Side Tracking: in short

To explain it in a few words, client side tracking works on the user's browser and is generally made using Javascript. The advantage is that it is kinda easy to collect some metrics and also lightweight on the server.

On the other hand, server side tracking doesn't use Javascript and is executed directly by the server itself. We might use PHP to analyze the requests we receive from our users.

There are also Log Analytics softwares like Awstats or GoAccess, which will analyze the server's log files to determine the views of the users on our web pages.

The main advantage of server side tracking and log analysis is that we can even monitor users that are making use of AdBlock or similar systems, which prevent the Javascript tracking code from working correctly.

How to setup server-side tracking with Matomo

Actually using server side analytics tracking with Matomo is pretty easy.

We will use the PHP Library as an example, because it is one of the most used languages when making websites.

  1. Download MatomoTracker.php and PiwikTracker.php from Github or any other server side tracking library
  2. Upload the MatomoTracker.php and PiwikTracker.php files in your web server, it might be in the folder /public_html/matomo/, using Filezilla or any other FTP software
  3. In our web application, we add the following PHP Code on all our pages, or in the template, based on what kind of tool we are using
# File template.php or similar, make sure this code is loaded in every page
$matomoSiteId = 1;
$matomoUrl = '{url-to-matomo-platform}';
$matomoToken = '{inser-auth-token-here}';
$matomoPageTitle = '';

require_once '{path-to-file}/MatomoTracker.php';

try {
    $matomoTracker = new MatomoTracker($matomoSiteId, $matomoUrl);
} catch (Exception $e) {

# File page.php, to customize the page title for Matomo
if (!empty($matomoTracker)) {

Let's see some more details:

  • $matomoSiteId is the id of the website configured on Matomo, you can find it in the Settings by going to Settings > Websites > Manage
  • $matomoUrl is the public url used by Matomo, e.g.
  • $matomoToken is a unique random code that needs to be configured (see the paragraph Configure the Auth Token)
  • $matomoPageTitle is the title of the page to send to Matomo, if you are using a CMS or Framework you will need to find a way to configure this variable properly, while if you are using single PHP files for every page you can add it in every file
  • require_once will load the MatomoTracker.php file, replace {path-to-file} with the actual path to get MatomoTracker.php, an example could be /var/www/html/
  • $matomoTracker will contain the MatomoTracker class with its own properties and methods
  • setRequestTimeout is used to give a maximum time to send a request to our Matomo: otherwise, if your Matomo server is not working, the page will be slowed down heavily
  • setTokenAuth will set the Authorization Token for Matomo
  • doTrackPageView is the function that sends the PageView evento to Matomo, it works the same way as in the Javascript code. It is mandatory to give this function a string to use as page title, it will then be used by Matomo in the visits report
  • the try/catch block and the if at the end are useful to prevent triggering PHP's Fatal Errors in case our Matomo istance is not responding

Configure the Auth Token

To configure the Auth Token in PHP, go in Matomo's Settings at the menu Settings > Personal > Security and at the bottom you will find Auth Tokens, press on Create new token.

Create a new Auth Token on Matomo
Create a new Auth Token on Matomo

You will need to enter your administrator password again, then you will be asked to give a description and generate the token. A random string will appear, and you might receive a security notification by email.

Insert a description to generate your token
Insert a description to generate your token

Token example: 2a96a7df4c6f09272bf445d1c753d4a8 (each token is unique)

Matomo Auth Token has been generated
Matomo Auth Token has been generated

After inserting the token into the PHP code we can test that the tracking is working as intended, by viewing the public website and verifying that the session is being registered by Matomo.

Can I use both Javascript and Server Side Tracking?

Yes, you will need to remove or comment the Javascript line that sends the PageView event to Matomo, otherwise you will find doubled views. I have tested this possibility and it can really happen to have duplicated visits if you use the pageview tracking both with Javascript and PHP.

Code sample:

var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
_paq.push(['enableHeartBeatTimer', 15]);
// The following line has been remove to avoid duplicated views
// _paq.push(['trackPageView']);
(function() {
    var u = "";
    _paq.push(['setTrackerUrl', u + 'matomo.php']);
    _paq.push(['setSiteId', '1']);
    var d = document,
        g = d.createElement('script'),
        s = d.getElementsByTagName('script')[0];
    g.type = 'text/javascript';
    g.async = true;
    g.src = u + 'matomo.js';
    s.parentNode.insertBefore(g, s);

You will see I have also used enableHeartBeatTimer, it is a function that allows to more accurately track the time spent by a user on the page, by sending a ping request to Matomo every N seconds (minimum 15). Also have a look at the Javascript documentation for Matomo.

You can also configure Event tracking on Matomo, like when you want to know which links are being clicked by your users.

Please be aware that some tracking modes will be blocked by the Do Not Track functionality in Firefox and other browsers, or by Ad blocking tools.

AdBlocker and Do Not Track

Most of the AdBlockers (AdBlock, uBlock and similar) will block the tracking initialized by Matomo. As an example, the word "matomo" might be banned, so any resource like matomo.js or matomo.php will not be loaded.

At the same time, the Do Not Track mode from Firefox will block some kinds of trackers, if the user's browser is using it and if the server does use the relative Header.

I have tested both these cases and they can be resolved with the server side tracking. Still, using Javascript to track some actions or events will be blocked anyway. You might want to configure your events tracking on the server side, but this will require more work.

You might build your links with a unique php file called link.php and this will take care to redirect the user to the correct page. Before doing so, it might send an event to Matomo in PHP. The main problem of this approach is that it will clearly make link and resources management harder, and it will require more data-entry from you.

Privacy concerns

Tracking those who do not wish to be tracked is a bad idea, but we don't necessarily need to give up on monitoring our views.

We surely need to do our best to respect a user's privacy. If we collect only aggregated data for statistical purposes, there will be no problems, but in case we want to perform remarketing and profilation, we will need to require the explicit consent to the user, and activate the tracking only after receiving it.

As an example, we might configure a PHP page to require consent and set a technical cookie if given.

After that we will verify that the cookie has been set and, in that case, we start tracking:

if (!empty($_COOKIE['matomoTrackingConsent'])) {
    # File template.php or similar, make sure this code is loaded in every page
    $matomoSiteId = 1;
    $matomoUrl = '';
    $matomoToken = '2a96a7df4c6f09272bf445d1c753d4a8 ';
    $matomoPageTitle = 'Page title';

    require_once '/var/www/html/yourwebsite/vendor/matomo/MatomoTracker.php';

    try {
        $matomoTracker = new MatomoTracker($matomoSiteId, $matomoUrl);
    } catch (Exception $e) {

    # File page.php, to customize the page title for Matomo
    if (!empty($matomoTracker)) {

Of course by doing so we might lose the first access, because we cannot activate the tracking before the user has given consent to do so.


Now your Matomo Server Side Tracking is set up!

If you liked this article, follow me on Facebook and subscribe our Youtube channel! If you need support write me in chat or by email!

Leave a comment

All comments will be subject to approval after being sent. They might be published after several hours.

You can just use a random nickname, it is usefull to allow me to at least answer your comments. And if you choose to submit your email, you can receive a notification whenever I reply to your comment.

No comments have been written so far on this article. Be the first to share your thoughts!