Matomo (formerly Piwik) – open source web analytics

Matomo is an open analytics platform currently used by individuals, companies and governments all over the world.

Installation

To start using the Matomo integration, you must have installed the django-analytical package and have added the analytical application to INSTALLED_APPS in your project settings.py file. See Installation and configuration for details.

Next you need to add the Matomo template tag to your templates. This step is only needed if you are not using the generic analytical.* tags. If you are, skip to Configuration.

The Matomo tracking code is inserted into templates using a template tag. Load the matomo template tag library and insert the matomo tag. Because every page that you want to track must have the tag, it is useful to add it to your base template. Insert the tag at the bottom of the HTML body as recommended by the Matomo best practice for Integration Plugins:

{% load matomo %}
...
{% matomo %}
</body>
</html>

Configuration

Before you can use the Matomo integration, you must first define domain name and optional URI path to your Matomo server, as well as the Matomo ID of the website you’re tracking with your Matomo server, in your project settings.

Setting the domain

Your Django project needs to know where your Matomo server is located. Typically, you’ll have Matomo installed on a subdomain of its own (e.g. matomo.example.com), otherwise it runs in a subdirectory of a website of yours (e.g. www.example.com/matomo). Set MATOMO_DOMAIN_PATH in the project settings.py file accordingly:

MATOMO_DOMAIN_PATH = 'matomo.example.com'

If you do not set a domain the tracking code will not be rendered.

Setting the site ID

Your Matomo server can track several websites. Each website has its site ID (this is the idSite parameter in the query string of your browser’s address bar when you visit the Matomo Dashboard). Set MATOMO_SITE_ID in the project settings.py file to the value corresponding to the website you’re tracking:

MATOMO_SITE_ID = '4'

If you do not set the site ID the tracking code will not be rendered.

User variables

Matomo supports sending custom variables along with default statistics. If you want to set a custom variable, use the context variable matomo_vars when you render your template. It should be an iterable of custom variables represented by tuples like: (index, name, value[, scope]), where scope may be 'page' (default) or 'visit'. index should be an integer and the other parameters should be strings.

context = Context({
    'matomo_vars': [(1, 'foo', 'Sir Lancelot of Camelot'),
                    (2, 'bar', 'To seek the Holy Grail', 'page'),
                    (3, 'spam', 'Blue', 'visit')]
})
return some_template.render(context)

Matomo default settings allow up to 5 custom variables for both scope. Variable mapping between index and name must stay constant, or the latest name override the previous one.

If you use the same user variables in different views and its value can be computed from the HTTP request, you can also set them in a context processor that you add to the TEMPLATE_CONTEXT_PROCESSORS list in settings.py.

User tracking

If you use the standard Django authentication system, you can allow Matomo to track individual users by setting the ANALYTICAL_AUTO_IDENTIFY setting to True. This is enabled by default. Matomo will identify users based on their username.

If you disable this settings, or want to customize what user id to use, you can set the context variable analytical_identity (for global configuration) or matomo_identity (for Matomo specific configuration). Setting one to None will disable the user tracking feature:

# Matomo will identify this user as 'BDFL' if ANALYTICAL_AUTO_IDENTIFY is True or unset
request.user = User(username='BDFL', first_name='Guido', last_name='van Rossum')

# Matomo will identify this user as 'Guido van Rossum'
request.user = User(username='BDFL', first_name='Guido', last_name='van Rossum')
context = Context({
    'matomo_identity': request.user.get_full_name()
})

# Matomo will not identify this user (but will still collect statistics)
request.user = User(username='BDFL', first_name='Guido', last_name='van Rossum')
context = Context({
    'matomo_identity': None
})

Disabling cookies

If you want to disable cookies, set MATOMO_DISABLE_COOKIES to True. This is disabled by default.

Internal IP addresses

Usually, you do not want to track clicks from your development or internal IP addresses. By default, if the tags detect that the client comes from any address in the ANALYTICAL_INTERNAL_IPS (which takes the value of INTERNAL_IPS by default) the tracking code is commented out. See Identifying authenticated users for important information about detecting the visitor IP address.