Buy Heatlens €299

Install and configure Heatlens

From the zip file to your first heatmap, in about fifteen minutes.

  1. Check the requirements
  2. Install the plugin
  3. Create a heatmap campaign
  4. Connect your consent banner
  5. Mask personal data
  6. Single-page apps
  7. Read and export reports
  8. Troubleshooting

1. Check the requirements

  • Heatlens for Matomo 5: self-hosted Matomo 5.14.1 or later, with PHP 8.1 or later.
  • Heatlens for Matomo 6: self-hosted Matomo 6.0 or later.
  • A Matomo super user account, and access to the server files or permission to upload plugins.
  • Your websites already track with Matomo through matomo.js or Matomo Tag Manager. Heatlens adds no tracking code of its own.

Heatlens does not run on Matomo Cloud, which does not accept third-party plugins.

2. Install the plugin

Option A: copy the files (recommended)

Unzip Heatlens.zip into the plugins/ folder of your Matomo, so that you get plugins/Heatlens/plugin.json. Make sure the web server user can read the files, then activate Heatlens under Administration → System → Plugins. From the command line:

cd /var/www/matomo
unzip /path/to/Heatlens.zip -d plugins/
./console plugin:activate Heatlens

Option B: upload the zip from Matomo

Matomo disables plugin uploads by default, for security reasons. To allow them, add this line under [General] in config/config.ini.php:

[General]
enable_plugin_upload = 1

Then go to Administration → Marketplace, choose Upload a plugin, select Heatlens.zip and activate it. You can remove the line again once Heatlens is installed.

3. Create a heatmap campaign

A campaign tells Heatlens which pages to record and how much. Go to Heatmaps → Manage heatmaps and create one:

Pages
Match by exact path (/pricing), path prefix (/blog/), exact URL or "URL contains". Query strings and fragments are ignored and never stored.
Devices
Desktop, tablet and mobile get separate heatmaps. Adjust the width breakpoints if your layout switches at other sizes.
Sampling rate
The share of eligible visits to record. Start at 100% on low-traffic pages, lower it on busy ones.
Recorded pages cap
The campaign stops recording once it reaches this number of page views.
Retention
How many days to keep the data. Leave it empty to follow your Matomo retention settings.

Site administrators can create, pause, resume and delete campaigns. Users with view access to the site can read the reports.

Heatlens records nothing until the visitor has agreed. If your site already uses Matomo's consent functions, Heatlens follows them:

_paq.push(['requireConsent']);
// once the visitor has agreed
_paq.push(['setConsentGiven']);

If your consent banner offers a separate choice for heatmaps, call these instead, only after the visitor has actually agreed:

_paq.push(['Heatlens.setConsentGiven']);
// when the visitor withdraws consent
_paq.push(['Heatlens.forgetConsentGiven']);

Consent to cookies alone does not grant heatmap consent. If Matomo tracking itself requires consent, that consent is needed too.

5. Mask personal data

Heatlens masks these elements in the visitor's browser, before anything is sent:

  • form fields: inputs, textareas, selects and editable areas;
  • any element with data-matomo-mask, data-heatlens-mask or data-matomo-ignore, and everything inside it;
  • as a fallback, email addresses and sequences of four or more digits found in text.

Keystrokes, field values, scripts and external stylesheets are never collected. A text pattern cannot recognise every name or address, so mark any area that shows personal data as plain text:

<div class="account-summary" data-heatlens-mask>
  Signed in as Jane Martin, 12 Rose Street
</div>

6. Single-page apps

Keep sending one Matomo virtual page view per navigation, as you already do for Matomo:

_paq.push(['setCustomUrl', location.href]);
_paq.push(['trackPageView']);

Heatlens starts a new recording after each page view. If a view finishes rendering much later, for example after loading data, call this once it is on screen. Don't call it on every component update:

_paq.push(['Heatlens.trackPageView']);

7. Read and export reports

Open Heatmaps and pick a campaign. Switch between clicks, movement and scroll depth, and between desktop, tablet and mobile. The scroll map shows the average fold line: what most visitors see before they scroll. Reports follow the Matomo date selector.

Export a report as JSON for your own analysis, or as a PNG of the heatmap overlay for slides and tickets.

8. Troubleshooting

The campaign stays empty

  • Check that the visitor gave consent: in a private window, accept your banner, then browse a page targeted by the campaign.
  • Check the sampling rate and the page rules: an exact path does not match /pricing/ if you entered /pricing.
  • Content blockers that block Matomo also block Heatlens.

Matomo does not load the Heatlens tracker code

Heatlens adds its code to matomo.js. If the web server cannot write that file, Matomo cannot update it on activation. Run this, then clear your caches:

./console custom-piwik-js:update
./console cache:clear

Still stuck?

Open a ticket on our support portal with your Matomo, PHP and Heatlens versions. See the support policy for response times.

See pricing Heatmaps and the GDPR