Home › web-analytics › Matomo Analytics step by step guide

Matomo Analytics step by step guide

web-analytics

14/01/2021 0

Matomo, formerly Piwik is a free and open source (more on open source software) web analytics application, that runs on a PHP/MySQL webserver. It tracks online visits to one or more websites and displays reports on these visits for analysis.

It is a good alternative for Google Analytics which protects users data and privacy. The main problem using Google Analytics is that our data is being compromised and it gets used for their own purpose

This software comes with community as well as enterprise edition. As we discussed in my earlier posts, the enterprise edition of Matomo version provides a richer feature set than the community version.

In this Matomo analytics step by step guide we will see from the beginning how to install and run Matomo on-premise, how to get and embed tracking code into different types of applications/websites. Also we will see how to install Matomo Docker as well.

so let’s get started!

Matomo installation

Minimum Requirements

To run Matomo (Piwik) your host needs below things:

Webserver such as Apache, Nginx, IIS, LiteSpeed, etc.
Matomo 3.x requires PHP version 5.5.9 or PHP 7.x. Matomo 4.x requires PHP version 7.2.5 or greaterMySQL version 5.5 or greater, or MariaDB
PHP extension pdo and pdo_mysql, or the mysqli extension.
Matomo can be run on any operating system such as Linux (Ubuntu, RedHat, CentOS, Raspberry Pi OS, etc.), Windows, macOS Server or FreeBSD.

Tracking 100,000 page views per month or less

One server to host both the database and app server
App server minimum recommended configuration: 2 CPU, 2 GB RAM, 50GB SSD disk.

Github repository

https://github.com/matomo-org/matomo

Matomo Installation using Softaculous

Search for “matomo” in the search section

On click of Matomo below screen will open, then click on Install Now

setup username and password and click Install

Done! You have successfully installed Matomo

login into Administrative URL to get the tracking code for your application. This code is used to track your application.

Please keep reading further, I have also covered how to track different types of applications using Matomo

Manual installation

Download Matomo from here https://builds.matomo.org/matomo.zip
Unzip the zip file to a folder on your hard drive. This will create a “matomo” folder containing the files and directories.
Open your FTP client and upload the Matomo files in ‘binary mode’ to the desired location on your web server. For example using the Filezilla FTP client, you can enable Binary mode transfer in the top menu Transfer > Transfer type > Binary). All files can be uploaded to a “analytics” sub-directory in your public www folder, for example http://yourdomain.org/analytics/ or you could setup Matomo in its own subdomain and upload all the files at http://analytics.example.org/

If you have SSH access to your server, you can use it instead of FTP as it is much faster: run

wget https://builds.matomo.org/matomo.zip && unzip matomo.zip

Open your web browser and navigate to the URL to which you uploaded Matomo. If everything is uploaded correctly, you should see the Matomo Installation Welcome Screen. If there are any problems, Matomo will identify them and help you out with a solution.

Docker installation

Here we will see how one can install using simple Docker.

First install Docker on your machine. Visit this page to choose version based on platform and install on your local machine

https://github.com/matomo-org/docker

Pull the docker image from Docker hub

docker pull matomo

Run the Matomo container and service as:

docker run -d --link some-mysql:db matomo

Once you’re up and running, you’ll arrive at the configuration wizard page. If you’re using the compose file, at the Database Setup step, please enter the following:

Database Server: db
Login: <MYSQL_USER>
Password: <MYSQL_PASSWORD>
Database Name: <MYSQL_DATABASE>

And leave the rest as default.

Then you can continue the installation with the super user.

Docker-compose

Pull the Matomo Docker sources from Github https://github.com/matomo-org/docker

A minimal set-up using docker-compose is available in here: https://github.com/matomo-org/docker/tree/master/.examples

docker-compose as example

services:
  db:
    image: mariadb
    command: --max-allowed-packet=64MB
    restart: always
    volumes:
      - db:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=
    env_file:
      - ./db.env

  app:
    image: matomo
    restart: always
    volumes:
#     - ./config:/var/www/html/config
#     - ./logs:/var/www/html/logs
      - matomo:/var/www/html
    environment:
      - MATOMO_DATABASE_HOST=db
    env_file:
      - ./db.env
    ports:
      - 8080:80

volumes:
  db:
  matomo:

Common issues and how to resolve them

Here is the list of common issues you might encounter while working with Matomo

All visitors have the same IP address and Provider. How do I track individual IPs?
Matomo tracks far fewer visits than other web analytics tools, but tracks the same number of pageviews.
The Real Time Visitors World Map is not showing data.
Matomo doesn’t track any visits and pages, and shows “There is no data for this report” in all reports.
Visits from search engines or campaigns are not recorded, Matomo shows “There is no data for this report” for all Referrers reports.
Matomo doesn’t track Downloads and clicks on Outlinks on my website.
Matomo doesn’t detect accurately the Country and/or Continent of my visitors.
Matomo is slow! It takes a long time to load widgets, reports and pages.
I get ‘Oops… there was a problem during the request.’ or ‘Internal Server Error’ or ‘500 error’ or the ‘White screen of death’. How do I proceed?
Matomo does not track visits on SSL / HTTPS pages.
Why do Matomo data reports differ from Google Analytics and other analytics tools?
After I updated Matomo, it stopped working (blank page, widgets not loading, error message, etc.). How can I fix this?
Matomo reporting UI doesn’t have any css style or, the menu text appears on a white background, or I get JavaScript errors in the Matomo UI. How to fix this display problem?
How do I configure Matomo on a server without Internet?
When tracking visits on an intranet website, Matomo assigns all page views to a few visitors who have very high page views count. How to fix it?
The Matomo Javascript code shows a red cross (on IE) or a broken image icon instead of the 1*1 transparent Pixel, what is the issue?
How do I configure Matomo when mod_security (or CA SiteMinder) is enabled?
How do I fix the error “Parse error: syntax error, unexpected T_STRING in …”
How do I solve issue ‘An error occurred: Cannot connect to the database’?
How do I fix the error “1118 Row size too large. The maximum row size for the used table type, not counting BLOBs, is 8126.”?
Why am I getting a warning about an untrusted hostname?
When included in an IFrame, Matomo reports do not load. How do I allow Matomo reports to load from within an iframe?
I’m a developer, how do I enable logging (and / or SQL profiling) in Matomo?

Please visit this page to get solution to above common issues in Matomo

Tracking your application using Matomo

Websites

You can use the JavaScript tracking client to track any website that supports JavaScript.

As mentioned earlier, login into your Matomo administrative URL and get the tracking code.

copy and paste the JavaScript tracking code into your pages, just after the opening <body> tag (or within the <head> section)

The tracking code looks as follows:

<!-- Matomo -->
<script type="text/javascript">
  var _paq = window._paq = window._paq || [];
  /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//<your-website-url>/";
    _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);
  })();
</script>
<!-- End Matomo Code -->

SPA (Single Page Application)

Single-page websites and web applications have become a standard over the last years. Tracking of such websites is crucial.

Use an existing integration for your framework

If you’re using a popular framework such as Angular, Angular JS, Vue.js, React Native, etc. then its recommend to first check if an integration may be available for your framework: see all available integrations for Matomo.

Embedding the Tracking Code

First you need to embed your JavaScript tracking code into your single-page website or web application as usual. To do this go to “Administration” in the top right in your Matomo instance, click on “Tracking Code” and adjust the tracking code to your needs.

Complete Example

In this example we show how everything works together assuming you want to track a new page whenever a hash changes:

var currentUrl = location.href;
window.addEventListener('hashchange', function() {
    _paq.push(['setReferrerUrl', currentUrl]);
     currentUrl = '/' + window.location.hash.substr(1);
    _paq.push(['setCustomUrl', currentUrl]);
    _paq.push(['setDocumentTitle', 'My New Title']);

    // remove all previously assigned custom variables, requires Matomo (formerly Piwik) 3.0.2
    _paq.push(['deleteCustomVariables', 'page']); 
    _paq.push(['trackPageView']);

    // make Matomo aware of newly added content
    var content = document.getElementById('content');
    _paq.push(['MediaAnalytics::scanForMedia', content]);
    _paq.push(['FormAnalytics::scanForForms', content]);
    _paq.push(['trackContentImpressionsWithinNode', content]);
    _paq.push(['enableLinkTracking']);
});

How to fetch Matomo (Piwik) data using HTTP API

Quering the reporting API

If you want to request data in any language (PHP, Python, Ruby, ASP, C++, Java, etc.) you can use the HTTP API. It is a simple way to request data via an HTTP GET.

You can, for example, get the list of countries where most of your visitors in the current month are from. Here is an example in PHP:

<?php

// this token is used to authenticate your API request.
// You can get the token on the API page inside your Matomo interface
$token_auth = 'anonymous';

// we call the REST API and request the 100 first keywords for the last month for the idsite=62
$url = "https://demo.matomo.org/";
$url .= "?module=API&method=UserCountry.getCountry";
$url .= "&idSite=62&period=month&date=today";
$url .= "&format=JSON&filter_limit=10";
$url .= "&token_auth=$token_auth";

$fetched = file_get_contents($url);
$content = json_decode($fetched,true);

// case error
if (!$content) {
    print("No data found");
}

print("<h1>Countries with most visits</h1>\n");
foreach ($content as $row) {

    $countryName = htmlspecialchars($row["label"], ENT_QUOTES, 'UTF-8');
    $hits = $row['nb_visits'];

    print("<b>$countryName</b> ($hits visits)<br>\n");
}

Here is the output of this code:

<h1>Countries with most visits</h1>
<b>United States</b> (50504 visits)<br>
<b>Australia</b> (23099 visits)<br>
<b>United Kingdom</b> (22298 visits)<br>
<b>Indonesia</b> (15631 visits)<br>
<b>Germany</b> (14497 visits)<br>
<b>Singapore</b> (10969 visits)<br>
<b>Philippines</b> (9974 visits)<br>
<b>Malaysia</b> (9419 visits)<br>
<b>India</b> (9195 visits)<br>
<b>Thailand</b> (8956 visits)<br>

Refer this API reference documentation for more insights

Reporting API Clients

Matomo provides different ready made API client libraries to invoke APIs. They are available for multiple languages lie PHP, Ruby, NodeJs, Python, Ruby, Laravel and C#

Refer this page for more detail.

Matomo License

Community and Enterprise version feature comparison

Community version basically comes with on-premise installation where you will install on-premise Matomo on your server. You will have to install and manage the infrastructure as opposed to the Enterprise version which is hosted on Cloud. And pricing is based on monthly traffic of your website. It comes with few out of the box features which are not available in Community version. You will need to develop such features on your own.

Below are the set of features which are available in both the versions of Matomo

eCommerce Tracking	Row Evolution	Scheduled Email Reports
Event Tracking	Transitions	Custom Alerts
Content Tracking	Overlay	HTTP Analytics API
Campaign Tracking	Privacy Options	HTTP Tracking API
User Tracking	All Websites Dashboard	Log Analytics
Site Search	Visitor Maps	Exportable Widgets
Real-Time	Visitor Profile	100+ Integrations
Customisable Dashboard	Site Speed	50+ Languages
Segmentation	Geo-Location	100+ Currencies
Custom Logo	Annotations	Timezone support

Feature comparison in Matomo Community and Enterprise versions:

Conclusion

So, in this article we have seen how to install Matomo on-premise software and how to start using it. We have also seen how to install the Matomo Docker version. The common issues guide will come in handy when you are stuck in the process. I have also shared features available in the Community and Enterprise version to give you an idea about different features Matomo is offering. Hopefully this will help you installing and choosing among different open source web analytics tools.

Happy to hear your thoughts. Please post it in the comments sections below.

References and links

Tags: how to track using matomo install matomo on local matomo analytics matomo analytics step by step matomo docker matomo docker compose matomo docker installation matomo step by step piwik web analytics