In this guide you will learn how to customize the tracking of Heatmaps & Session Recordings. By default, you do not need to change your tracking code and Matomo (formerly Piwik) takes care of everything. However, you can adjust the tracking in various ways.
If you have already embedded the Matomo JavaScript Tracking Code into your website,
the Heatmap & Session Recording will automatically start tracking user activities. The tracking code is directly added
in your Matomo JavaScript tracker file /matomo.js as long as the file matomo.js in your Matomo directory is writable
by the webserver/PHP.
To check whether this works by default for you, login into Matomo as a Super User, go to Administration, and open the "System Check" report. If the System Check displays a warning for "Writable Matomo.js" then learn below how to solve this.
To configure the recording of a session or a heatmap, log in to your Matomo and click on "Heatmaps => Manage" or "Session Recordings => Manage".
There you will be able to configure on which pages you want to record activities and how many sessions should be recorded. Matomo will automatically detect any configured heatmap or session recording and start recording activities when needed. You don't need to change your tracking code or your website to configure .
To detect if any activities need to be recorded, an HTTP request will be issued on each page view to your Matomo. While this request is
fast and does for example not connect to your database, it may still add a bit of load to your server. If you want to avoid such
a request on each page view, have a look at the API reference for addConfig().
When you record a session or generate a heatmap, Matomo may record user sensitive data which is displayed on your website. To mask such content which is not displayed as part of a form element (see above) but any other element (such as a <p> or <div>), you can use the data-matomo-mask attribute as well. The data-matomo-mask attribute works from version 3.1.9 of Heatmap & Session Recording.
You can mask an individual element like this:
<span data-matomo-mask>Firstname lastname</span>
Alternatively, you can mask a set of elements within your web page by specifying the data-matomo-mask attribute on an element that is higher in the hierarchy:
<div data-matomo-mask>
<p>
<span>Firstname</span>
<span>Lastname</span>
</p>
</div>
When the content is masked, each character will be replaced by an asterisk (*) before sending the data to Matomo. It will also mask any content that is shown in a title, alt, label or placeholder attribute.
When you record a session, Matomo may record keystrokes that a visitor enters into a form field depending on your session recording
configuration. By default, no keystrokes are captured. If the feature to record keystrokes is enabled, Matomo will record any text entered into form fields and replay them later
in the session recording video but any entered text will be "masked". This means any text entered into such a masked field will be replaced with asterisks, for example secure may be tracked as ******.
If you wanted to record keystrokes for some form fields in plain text, you need to enable the capturing of keystrokes in the session recording and specifically whitelist
in the HTML of your website or app which form fields are OK to be recorded by specifying a data-matomo-unmask attribute. There is also a data-matomo-mask
attribute to prevent the recording of sensitive information if a parent was whitelisted.
Please note that some fields, such as passwords, common credit card fields, and some other fields will be always masked to prevent the recording of potential personal or sensitive information in plain text.
You can unmask an individual form field like this:
<input type="text" name="example_field_record_plain_text" data-matomo-unmask>
Alternatively, you can mask a set of form fields within your web page by specifying the data-matomo-unmask or data-matomo-mask attribute on a form element like this:
<form data-matomo-unmask>
<div>
<input type="text" name="example_field_record_plain_text">
<input type="text" name="tax_number" data-matomo-mask>
<input type="text" name="passport_id" data-matomo-mask>
</div>
</form>
To force that no keystrokes will be recorded even when enabled in the UI, call _paq.push(['HeatmapSessionRecording::disableCaptureKeystrokes']);
If disabled, no text entered into any form field will be sent to Matomo, not even masked form fields.
matomo.js in your Matomo directory file is not writableWhen your Settings > System Check reports that "The Matomo JavaScript tracker file matomo.js is not writable
which means other plugins cannot extend the JavaScript tracker." then you have two options to solve this issue:
matomo.js file writable, for example by executing chmod a+w piwik.js or chown $phpuser piwik.js (replace $phpuser with actual username) in your Matomo directory.
We recommend running the Matomo console command ./console custom-matomo-js:update after you have made the file writable.<head>:
<script src="https://your-matomo-domain/plugins/HeatmapSessionRecording/tracker.min.js">Note: Loading the tracker file manually won't work if you are using Matomo for WordPress. The Matomo JS tracker will automatically include the tracking code so loading it manually won't be needed. To find the correct path for the Matomo JS Tracker file see the Matomo Endpoints section in the Matomo for WordPress System Report. In most cases the path looks like this: //your-matomo-domain/wp-content/uploads/matomo/matomo.js. Matomo for WordPress will automatically use the correct path unless you configure the tracking code manually.
Yes, there are:
matomo.js ever becomes writable, the HeatmapSessionRecording tracker would be loaded twice (in such a case the tracker notices it was already initialized and won't track everything twice)If possible, we recommend making the matomo.js file writable.
Now that you've completed the setup, you may want to read the Heatmap & Session Recording developer FAQ, or learn more about the Heatmap & Session Recording JavaScript API.