What does Heatmap & Session Recording do?

Heatmap & Session Recording tracks interactions like clicks, mouse movements, scrolls, form interactions and page changes.
These interactions can be afterwards replayed in a video or visualized in a heatmap so you can find out what your visitors are really looking for, where they think something is clickable but it is not, and much more.

Heatmap & Session Recording gives you full control over your data and 100% data ownership.

Where can I get the Heatmap & Session Recording?

Heatmap & Session Recording is a plugin for Matomo and is available for purchase on the Matomo Marketplace as a yearly subscription. While the subscription is active, you will receive all updates for this plugin.

You can also get it as a hosted solution on our Matomo Analytics (formerly Piwik Analytics) Cloud.

Where do I get more information about the Heatmap & Session Recording plugin?

It is recommended to visit the Heatmap & Session Recording website as well as the Heatmap & Session Recording plugin page on the Matomo (Piwik) Marketplace for a full list of all benefits and features. Developer documentation can be found on the Developer Zone.
There is also a Heatmap User Guide and a Session Recording User Guide.

Who develops & maintains the Heatmap & Session Recording plugin?

The plugin is developed and maintained by InnoCraft, the company from the makers of Matomo (Piwik). At InnoCraft, talented and passionate product designers and engineers build and maintain the free and open source project Matomo. This ensures the highest quality and compatibility of all their plugins. As a result, popular Matomo features such as Segmentation work out of the box.

What about the quality of the Heatmap & Session Recording plugin?

This plugin is built and maintained by InnoCraft, the makers of Matomo (Piwik). This ensures that the plugin is well integrated, kept up to date and automatically tested whenever a change in Matomo core is made. By purchasing this plugin, you also support the developers of Matomo to maintain the free and open source analytics platform itself.

Does Heatmap & Session Recording work as a standalone product?

No, the Heatmap & Session Recording plugin is built on top of Matomo Analytics (formerly Piwik Analytics). To use it, you first need to install Matomo. Matomo requires PHP, a MySQL database and a webserver like Apache or Nginx. Learn more about Matomo.

Alternatively, to take away the hassle of installing and maintaining your own Matomo, signup to our Matomo Cloud (formerly Piwik Cloud) service.

Which Matomo version is required for this Heatmap & Session Recording plugin?

Matomo (Piwik) 3.0.4 or newer is required. You can also signup to our Matomo Cloud (formerly Piwik Cloud) service.

Which browsers are supported and measured by Heatmap & Session Recording?

The plugin has been tested with several browsers, devices and operating systems.

  • Viewing the generated heatmaps and recorded session videos works in all browsers that Matomo (Piwik) supports as well (eg IE10+, Edge, Chrome, Firefox, Safari, …).
  • Tracking heatmap activities works on pretty much all browser versions, even older versions of Firefox, Chrome, and others. Only Internet Explorer requires at least version 10.
  • Recording sessions works on pretty much all browser versions as well, even older versions of Firefox, Chrome, and others. Only Internet Explorer requires at least version 11.
  • The tracker has been tested even on older browsers like IE6+ and won’t break your website. If a browser is not supported it will simply not record activities and not affect your website in any way.

What does Heatmap & Session Recording look like?

You can find screenshots of the UI in the plugin preview.

There is also a video showing you how a replay of a recorded session looks like:

Is it complicated to set up the tracking of Heatmaps and Session Recordings?

No, in fact everything works out of the box and you don’t even have to change your website or tracking code. Matomo (Piwik) will automatically discover when to record heatmap or session recording activities.

To learn all details about the tracking of heatmaps and session recordings, check out our Heatmap & Session Recording developer guide.

How do I get started tracking my heatmaps & session recordings?

  • To generate a heatmap, log in to your Matomo (Piwik) and click on “Heatmaps => Manage” either in the reporting menu or the administration menu.
  • To record sessions, log in to your Matomo and click on “Session Recordings => Manage” either in the reporting menu or the administration menu.

How do I mask entered keystrokes on individual form fields?

When you configure a session recording, you can choose to optionally record keystrokes, that is text entered by your visitors into text form fields.

If enabled, Matomo (Piwik) will capture these keystrokes and track them so they will be shown when you replay the recorded video. Matomo will automatically mask password form fields and common credit card form fields. If you want to mask additional form fields, simply add a data-matomo-mask attribute to an element. Learn more about masking keystrokes.

Note that Credit Card fields are automatically masked and not tracked (learn more)

You can also mask (hide and exclude) from Session recordings and Heatmaps any content in your website: learn more.

How do I disable the recording of any keystrokes?

See the developer FAQ How do I prevent the capturing of keystrokes when recording a session?

How do I disable the recording of any mouse and touch movements?

See the developer FAQ How do I disable the recording of mouse and touch movements?

Which Heatmap types are supported?

You can view click, mouse move and scroll heatmaps.

  • The Click Heatmap shows you where your visitors clicked on a web page. This lets you for example detect where your visitors think that something is clickable but it is not.
  • The Mouse movement Heatmap shows you where your users moved the mouse on your web page. This lets you for example detect what users are looking for and where they are going next.
  • The Scroll Heatmap type shows you how far down your visitors scroll on your web page. This lets you for example find out whether your page structure is good, and how often users scroll down.

The heatmap visualization also shows you the “Average above the fold” position letting you see how much of your web page is actually visible without scrolling when they view your web page.

Is the recorded heatmap & session recording data accurate?

Yes, we have put lots of effort to track accurate data by tracking the data in a very particular way. Instead of tracking fixed pixel positions like many competitors do, we track relative positions to elements within your web page. This ensures that session recording videos and generated heatmaps are accurate. As we record relative positions, the shown visualizations and videos are still accurate even if you view them in a different browser or operating system, if the font used is different, if the zoom level is different, and even if the screen resolution is different.

What extra resources and storage size do I need to consider when using Session recording?

Session recording captures a screenshot of your page then mouse clicks, scrolls and coordinates as well as keystrokes if enabled. This data is then replayed across the screenshot in the playback window. The process is very efficient and should not require any further resources than normal. Session recording is not captured in a video format such as AVI or MP4 that can be downloaded.

Sessions are stored in the database and aren’t too large. The exact size depends on the website and the number of average page views. They are stored efficiently to minimize storage space. For example they are compressed (like a zip file) and the same stored recorded HTML is re-used again whenever possible. Also when a recording is deleted later, they will be completely removed. So even storing 100.000 and more recordings will not be an issue.

Can I change the resolution when viewing a heatmap?

Yes, you can choose between lots of different widths when you view a heatmap and the recorded data will automatically adjust. You can find the select field at the bottom of the heatmap visualization.

How do I delete an already taken heatmap screenshot?

You can delete an already taken screenshot of a heatmap by navigating to a heatmap and scrolling to the bottom of the page. If the heatmap is still active and you have at least write access, then you will be able to delete the screenshot.

The screenshot will be retaken in the near future as soon as a visitor views the page again.

If the heatmap is no longer active, it is not possible to delete the screenshot because the screenshot would not be retaken (unless below command is used).

Alternatively, there is an API method such as:


As well as a Console command:

./console heatmapsessionrecording:remove-heatmap-screenshot

The console command can also be used to retake the screenshot of an already finished heatmap. In this case, the heatmap will be temporarily restarted and up to 50 new samples will be taken so a screenshot can be taken. Then the heatmap will end automatically.

Which activities are replayed in session recording videos?

The following events are tracked and replayed in a video:

  • Clicks
  • Mouse movements
  • Current cursor position
  • Scrolls
  • Window resizes
  • Zoom on mobile devices
  • Form changes such as keystrokes on text fields and changes on radio, checkbox and select fields
  • Page changes. For example if a pop-up appears, or if a page changes in any other way you will see these changes in the video as well

The video timeline indicates when a certain event occurs so you can see at a glance what you can expect to happen when you replay the video, and it is easy to quickly jump to specific activities.

How do I replay a recorded session?

As soon as you have configured a session recording, Matomo (Piwik) will start tracking activities of your visitors so you can replay them in a video. To replay these activities, log in to your Matomo and select “Session Recordings” followed by the name of your configured session recording.

You will see a list of all recorded sessions including the information when it was recorded, how much time they spent on the page, the resolution of the visitors’ viewport, the location, device, operating system and browser. To replay such a video, hover on a session recording row and select the big red play button.

How do I view more information about the visitor of a recorded session?

For each recorded session we show you a bunch of information like the location and device that was being used when the session was recorded. To get even more information about a visitor, hover a row and click on the Visitor Profile icon.

When you replay a video, you can also select the visitor profile icon in the middle/top right area.

Which shortcuts can I use when replaying a session recording video?

  • space or k to pause or play the video
  • left arrow key to jump backwards 5 seconds
  • right arrow key to jump forwards 5 seconds
  • j to jump forwards 10 seconds
  • l to jump forwards 10 seconds
  • 0, space or k to replay the video if it finished
  • n play next page view of this visitor within this session
  • p play previous page view of this visitor within this session
  • a enable / disable auto play of next page view within a visit
  • b enable / disable skip pauses
  • s change replay speed

How do I record only sessions when a visitor spend at least a specific time on my page?

When you configure a session recording, you can define a minimum time a visitor needs to spend on an individual page before the session is actually recorded. This way you don’t end up with too many recordings that might be only a few seconds long.

How do I avoid having recording sessions that contain no activity?

When you configure a session recording, you can choose whether a session should be recorded only if there has been at least a click and a scroll. This is enabled by default so you don’t end up having recordings with no actions.

If you also want to replay recordings with only a click, only a scroll, or no activities, you can disable this setting in Matomo (Piwik) > Session Recordings > Manage.

How do I delete a recorded session?

To delete a recorded session go to the Session Recording report and hover the session you want to delete. Now a “trash” or “bin” icon will appear next to the “play” icon. As soon as you click on it, the recorded session will be deleted.

Is it possible to apply segments and view recorded sessions and heatmaps for a custom segment of my users?

Yes, Heatmap and Session Recording lets you slice and dice your analytics reports exactly how you need to extract valuable insights into your visitors. You can apply over 100 Matomo (Piwik) segments. For example, view sessions for returning visitors or view sessions for visitors who converted a specific goal.

How do I disable the tracking of all heatmaps and session recordings for a specific site?

You can prevent the tracking of any activities by calling _paq.push(['HeatmapSessionRecording::disable']); in your website’s analytics tracking code. This is especially useful when you want to record activities only for some of your websites, but not for all of them.

Does Heatmap & Session Recording work with a single-page websites and web applications?

Yes, they are fully supported out of the box. Read more about this in the Heatmap & Session Recording API Reference, or learn more about tracking single-page application in our FAQ.

Can I track activities only on a portion of my visitors?

Yes, when you configure a heatmap or a session recording, you can define a so called “sample rate”. You can choose a rate between 0.1% and 100%. If you choose for example 10%, only every 10th page view will be recorded.

How do I track only a specific target group?

You can specify a custom trigger method to track for example only logged in users, only users with a certain age, from certain locations, or only track activities during the day using the HeatmapSessionRecording::setTrigger tracking method. Learn more about this feature in the Developer FAQ.

Does Heatmap & Session Recording work with mobile and tablet devices?

Yes, Matomo (Piwik) will automatically detect the device type of your visitors. In case the device type could not be detected automatically, you can define pixel thresholds to indicate when we should assume a device is a mobile or tablet device. To not having to configure these tablet and mobile thresholds every time you configure a heatmap, you can change them globally under “Administration => General Settings”.

You can view the heatmap data for desktop, tablet, and mobile users separately and of course you can apply any Matomo segments to heatmaps and session recordings.

Can I generate several heatmaps and several session recordings at the same time?

Yes, you can. There are no limits to how many pages you target at a time.

How can I target specific pages when configuring a heatmap or session recording?

The plugin lets you define page rules based on “URL”, “URL path”, and “URL parameter”.

To match a specific value, you can select different comparisons like “equals simple”, “equals exactly”, “starts with”, “contains”, “matches a regular expression”, “not equals simple”, and many more.

When you choose “equals simple”, the protocol (http or https), any URL parameter and trailing slashes in a path are ignored letting you more easily match different versions of a page URL. On the contrary, when selecting “equals exactly”, the value has to match exactly.

You will need to define each page you would like to track.

How do I ensure my configured target pages actually match the URL I want to match?

To make sure your defined target page rules match the page URL you want to match, use the URL validator which is displayed next to your target page rules. By entering the URL into the URL validator, you will see visually whether the entered URL would be matched by your page rules or not.

What do the different rule types mean?

When you configure a heatmap or a session recording, you can configure several rules to define on which pages these feature should be activated.

To define one or multiple rules, you first need to choose on which value your rule should be based on, for example URL, Path and URL parameter. When the URL is for example https://www.example.com/blog/2017/01/?page=1&limit=10, then URL is equal to the full URL, Path is equivalent to /my/test/url/ and a URL parameter could match page or limit.

Now you can select how your expected value should be matched. You have various options, for example:

  • equals simple This comparison is only valid for URLs but not for paths or URL Parameters. When comparing the URL with your expected value, it will ignore the URL protocol, all search parameters, a www subdomain, and a trailing slash. This means the above URL would also match for example http://example.com/blog/2017/01 as the protocol (HTTP or HTTPS) may be different, www. subdomain is ignored, and any URL parameters such as page or limit are ignored in the comparison as well. If your page uses HTTP and HTTPS, or if you have the same page available under different URL parameters and you want to match all of them, this is typically a good choice.
  • equals exactly In this case the rule will be only activated when the visited URL is exactly https://www.example.com/blog/2017/01/?page=1&limit=10. The rule would not be activated when the URL starts for example with http:// or when the URL has different or no URL parameters.
  • contains This comparison allows you to test whether the value contains a certain value. If you wanted to match for example all blog pages for the year 2017, you could define a rule where the URL or path contains blog/2017.
  • starts with When you select this comparison, the value has to start with this value. For example, you may want to match all URLs that start with https://www.example.com/blog/. Because the comparison is performed exactly, it wouldn’t match when someone visits http://www.example.com/blog/ (HTTP instead of HTTPS).
  • regular expression Regular expressions give you the most flexibility but are also the most challenging ones. Regular expressions are usually defined by developers and allow you match a value in pretty much any way you want.

Please note that all comparisons are performed case-insensitive. This means a value matches a rule no matter if the domain is written for example www.Example.com or www.example.com.

For all comparisons there is also their counterpart available that allows you to exclude a certain value. For example, you can make sure a certain value doesn’t start with a specific value by selecting “Not starts with”.

We know it can be challenging to coming up with these “rules” and often you can use multiple comparisons to achieve the same thing. To help you define these rules, our UI includes a tool to easily help you validate whether a certain rule actually does what you had in mind or not.

How do I hide (exclude) certain elements of my web page when viewing a heatmap?

When you configure a heatmap, you can define one or multiple CSS selectors to hide elements within your web page. This is useful if your website shows for example a pop-up when a user lands on your website. If you don’t want to configure the same CSS selectors each time you create a heatmap, you can define custom stylesheets in your CSS.

To find the CSS selector for a certain element on a web page, right click on the part you want to hide on your web page and then select “Inspect element”. This should work in most modern browsers. Now right click on an element you want to hide and select “Copy > Copy selector”.

How do I specify a screenshot URL for a heatmap?

When you configure a heatmap and define on which pages the activities for this heatmap should be recorded, different URLs may match your defined page rules. For example when you configure a page rule like “record all activities when page URL starts with https://matomo.org/blog”, URLs like “https://matomo.org/blog/2016” and “https://matomo.org/blog/2017” may match.

If you want to capture the screenshot only on a specific URL, for example only on “https://matomo.org/blog/2017”, you can configure this URL when configuring your heatmap as a “screenshot URL”.

You may also be interested in How do I delete an already taken heatmap screenshot?

How do I download a generated heatmap?

We are working on the possibility to directly download the generated heatmap as an image. As a workaround, you may use the “Print to PDF” feature in your browser to keep a copy of a heatmap. There are also various browser extensions that lets you capture screenshots and download it as an image.

How do I stop recording further heatmap or session recording activities?

If you want to stop the recording of any activities before the configured limit is reached, go to “Heatmaps => Manage” or “Session Recordings => Manage” and click on the “stop” icon in the “Actions” column.

Is there a maximum page height for heatmaps?

No, while many other solutions have problems showing heatmaps for pages that are larger than 8.000px or 32.000px, Matomo (Piwik) will render it nicely for any page length.

Will the generated heatmaps and recorded sessions still work even if I remove the page on my website?

Yes, the heatmap and recorded sessions will still work when you remove the page from your website.

How do I correct a heatmap when a page header is shown over the full heatmap?

If you use “Parallax Scrolling”, or when a part of your page is set to 100% of the browser height, the heatmap might not be shown correctly. Typically, the header would be shown stretched over the whole heatmap and other parts of the web page would not be visible. To solve this problem, set a max height to this element using CSS or JavaScript. For example:

.welcome { max-height: 1000px; }

If you want to set this style only for Heatmaps, you can prefix your selector with “html.piwikHeatmap”:

html.piwikHeatmap .welcome { max-height: 1000px; }

The chosen 1000px is only an example, you can set it to any height. Learn more about custom stylesheets.

How do I apply custom stylesheets when a heatmap is generated or a session recording replayed?

There are several ways to apply custom CSS when rendering Heatmaps and Session recordings:

  • To apply custom CSS stylesheets to your Heatmaps and Session Recordings, prefix your CSS with html.matomoHsr (recommended) or html.piwikHsr.

  • To apply custom stylesheets only for Heatmaps, prefix your CSS with html.matomoHeatmap (recommended) html.piwikHeatmap.

  • To apply custom stylesheets to Session Recordings, prefix your CSS with html.matomoSessionRecording (recommended) or html.piwikSessionRecording.

  • To load and apply a custom stylesheet file only to your Heatmaps and Session recordings, add the following CSS code to your HTML page or CSS: html.matomoHsr { @import url("fixed.css"); }.

Custom stylesheets can be useful to prevent any possibly sensitive data from being shown in a heatmap or a session recording. It can be also useful when your website shows a pop-up when a user lands on your website. Under circumstances such a pop-up could be visible in a heatmap. You can also exclude or hide elements when you configure a heatmap, but by defining it in your stylesheets you don’t have to configure it each time you create a new heatmap.

Will the generated heatmap still work if I change a web page while heatmap data is collected?

Yes, editing your web page should not affect the results and the heatmap data will be still correct and show you where your users really engage.

What can I do if the heatmap or session recording is not styled and CSS or font icons seem missing?

When Matomo (Piwik) records activities for heatmaps and session recordings, the HTML of your website is being recorded and shown when you view a heatmap or a recorded session. However, the CSS and images that your web page embeds will still be loaded from your website.

  • If you have removed CSS or image files from your website that are embedded within the recorded HTML, then the styles might not be shown anymore in the Heatmap or Session recording. However, any generated heatmap data or recorded session will be still correctly displayed, because we track activities in a special way with maximum accuracy. Matomo tries to store the entire CSS of each webpage in the database. In some cases this may not work see this FAQ when you load the CSS from a different domain. If you are loading cached CSS version with unique file names such as cache/223ks2j3jdmam4.css from a different domain and you cannot fix this CORS issue, you can instruct Matomo to load the uncached CSS version or an always existing CSS file by change the HTML structure and setting a data-matomo-href attribute: <link href="cache/223ks2j3jdmam4.css" data-matomo-href="uncached.css">. In this case Matomo would load the uncached.css file when viewing the heatmap.

  • If you have not removed CSS files but your heatmap or session recording is still not styled, your website might not support HTTPS. In this case, try to access your Matomo via “http://” instead of “https://”. We recommend that you keep using Matomo via “https://” and create a HTTPS certificate for your website in order to make sure the stylesheets are applied.

  • If you have not removed CSS files, and your website supports HTTPS, and some of your CSS or fonts or font icons are still not loaded in the Heatmap or Session recording, and your website is on a different domain name as your Matomo instance, the problem may be that your website does not allow cross domain requests (CORS). To confirm this is the issue, when viewing the heatmap or session recording, you can check your browser developer console (in the tabs ‘Console’ and ‘Network’), whether you see any error: Access to Font at https://website.com from origin https://piwik.example.com has been blocked by CORS policy:
    No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'https://piwik.example.com' is therefore not allowed access.

    If you see this error in the browser, the solution is to configure your website and enable CORS by outputting a HTTP header Access-Control-Allow-Origin: * in your website responses or better instead of using a * define the Matomo tracking domain for CSS files Access-Control-Allow-Origin: https://matomo.example.com. (Contact your webmaster for more information)

  • If you are using a browser extension such as Privacy Badger or other Adblockers, they may be blocking some of your website resources from loading. Please try to disable the extension on your Matomo domain name or URL, and refresh the page.

  • If the heatmap or session recording is still not styled, please contact us and we will investigate.

Can I record more than 5000 sessions at once?

Yes. By default, the UI allows you to record only up to 5000 sessions for a single recording. In case you wanted to record more than 5000 sessions, you can change your config/config.ini.php file by changing the session_recording_sample_limits value. If you cannot find this setting in your config file, please add the following two lines and adjust the values to your liking:

session_recording_sample_limits = "50,100,250,500,1000,2000,5000"

Setting a higher limit is usually not needed as it takes about 28 hours to watch 5000 sessions with an average length of 20 seconds. However, this can be useful if you want to record many, if not all sessions on your website and then apply segments afterwards to drill down the sessions you are interested in.

Note: You can create unlimited recordings but the sample limit per recording is limited to 1 Million. At an average of 30 seconds per sample will take 1 year of non-stop watching to watch 1 Million samples.

Why does the Heatmap screenshot not show the fully rendered page (pictures or content missing)?

The screenshot for a Heatmap is taken when the page is officially loaded according to the browser. In some cases, the browser may consider the page fully loaded and rendered before all components are actually loaded. For example, when you lazy load certain images or other resources for a faster page load time. This means the load event triggered by the browser is not reliable and you need to manually tell Matomo (Piwik) when the site is considered loaded to see a fully rendered screenshot in the Heatmap. To do this, follow these steps:

1) Disable Heatmap & Session Recording in your tracking code (as early as possible eg when calling “setSiteId” etc):


2) Enable Heatmap & Session Recording as soon as the page is considered fully rendered within your code:


Please note that when you manually disable the Heatmap & Session Recording, then Matomo will only start recording the session when you have re-enabled it (once the page was fully loaded). As a result, any interaction that occurred before the page was fully loaded will not be recorded. In general, we recommend to try and make your pages load faster so that your visitors have a better user experience and you do not experience this issue as much.

Can anonymous users view session recordings?

Matomo (Piwik) allows you to make reports public and viewable by anyone. If you do make the data for a specific website or mobile app public, your reports are accessible without having to log in. As Session Recordings may contain sensitive data, it won’t be possible to replay session recordings and neither see which sessions were recorded for privacy reasons: for example the recorded sessions may contain keystrokes typed by users and more.

Does Heatmap & Session Recording set any cookies?

When you record sessions, a first party cookie will be set for the duration of the visit named _pk_hsr. This cookie is needed to ensure that all page views within a users’ session will be recorded. The cookie will be only set as soon as a user has reached a configured entry page. If you disable cookies via the tracking code, the plugin will respect this setting and not set a cookie. As a result, not all page views within a session may be recorded if you set a sample rate of lower than 100% or configure an entry page. A possibly configured cookie domain or cookie path will be respected. Learn more about Matomo (Piwik) JavaScript Tracker cookies.

Can I fetch Heatmap and Session Recording reports via the Matomo HTTP Reporting API?

Yes, all recorded activities can be fetched in different formats such as JSON, XML, CSV, HTML and more, so you can integrate this data anywhere and perform custom analysis on it. You can also configure the recording of new heatmaps or session recordings via the API, stop the recording, delete recordings, and more. Read more about the Matomo (Piwik) HTTP Reporting API and view the Heatmap & Session Recording Reporting API Reference.

Matomo is not recording any Heatmaps or Sessions, what can I do?

First, we recommend to open your Heatmap or Session Recording configuration in the Matomo (Piwik) UI to make sure you have configured a correct target page or entry page. There is a URL validator just next to the page configuration that lets you check if a heatmap or session would be recorded on a certain page URL. This way you can find typos and other configurations problems.

If your configuration is correct, likely the request to $yourPiwikDomain/plugins/HeatmapSessionRecording/configs.php fails because of restrictions in your web server configuration.

Please log in to your Matomo as a Super User and go to Administration => System Check. There is a system check for Heatmap & Session Recording that checks whether the file is accessible from the internet / intranet or not. If not, you will see an error message explaining the problem.

If the system check says everything is ok but it still doesn’t work, you can also check manually if the file “configs.php” file is accessible. Open your website, right click and select “Inspect”. Now go to the network tab and reload your website. You should see an entry for “configs.php” with a status of “200 OK”. If there is a status like “403”, then you need to modify your web server to allow access to this file.

Please note: When manually checking if the configs.php is available from your browser you may see a “400 Bad Request” response. This is the expected response when no parameters are sent and indicates that access to the configs.php file is not being blocked.

If you are using Cloudflare or something similar, you may need to invalidate your cache for the Heatmap tracking code to appear in your “piwik.js” tracking file. You might also want to edit your “config/config.ini.php” file and add or modify the following two lines:

add_tracking_code_only_when_needed = 0

Still not working? Please get in touch with us, we are happy to help.

Do I get access to the raw data that was tracked, such as clicks and mouse moves?

Yes, you get access to all data that is stored in your MySQL database: the data is stored in the matomo_log_hsr* tables.

You can also access the data via the API. let’s say you want to export a specific recording that can be found at the following https://matomo.yoursite.example/index.php?module=HeatmapSessionRecording&action=replayRecording&idSite=4&idLogHsr=67&idSiteHsr=2

For querying the raw data you need the idSite and idSiteHsr of the site and the idLogHsr of this recording.

When you now provide them to the HeatmapSessionRecording.getRecordedSession API, you get the full raw data of this visit (every mouse movement, scroll, etc.)


If you now want to get the data of multiple visits, you can use the getSessionRecordings and getRecordedSessions to get the idLogHsr in an automated way.

More details about the Heatmap & Session Recording API can be found here.

Under what license is the Heatmap & Session Recording tracker released?

Heatmap & Session Recording and Heatmap & Session Recording tracker are released under the InnoCraft EULA.

Is there any data limit to how heatmaps can be generated or how many sessions can be recorded?

No, there is no data limit with the Heatmap & Session Recording product. You can generate as many heatmaps and record as many sessions as you wish. Learn more about No data limit.

How do I exclude employees or partners views and interactions from the heatmap & session recording reports?

See our FAQ: Excluding traffic from Matomo (Piwik) using IP Addresses, Cookies, and more.

How can I share a heatmap?

There could be a scenario where you may need to let someone view the Heatmaps without logging in to Matomo, in this instance you can share a link of Heatmaps report.

Please follow the steps below:
1. Login to Matomo as Super User
2. Create a new user with View permission
3. Log out of Matomo
4. Login again as the newly created user
5. Create a new token_auth
6. Copy the token_auth created and save it
7. Click on Dashboard and Heatmaps > Manage Heatmaps
8. Click on the View (eyeball icon) and you will be redirected to a new tab
9. Append &token_auth=paste_created_token_here at the end of the URL

Note: As the token will be publicly visible make sure you only create a View only permission user, also note whoever can see the Heatmap report would be able to also access all of the Matomo data for this website. It is also possible to embed this report in an iFrame in a different website.

How long can I keep Heatmaps and Session recordings?

If you use self-hosted Matomo, heatmaps and session recordings are kept indefinitely.

If you use Matomo Cloud, heatmaps and session recordings are kept for 3 months.

Why do I have heatmap samples but no screenshot?

When viewing your heatmap samples you may see the following message in the UI:

There have been XX samples recorded so far. However, no screenshot has been taken yet. If there is a “Screenshot URL” for this heatmap, it may take a while for the screenshot to become available as a user first needs to open this screenshot URL. Depending on the sample rate this may take a while.

The most likely reason for this is the security settings of your website. When you first visit a web page configured for a heatmap the entire DOM (page markup) is captured and saved in your Matomo database. This is then used later for displaying your heatmap in the samples screen. This initial request can sometimes be very large and some Web Application Firewalls or security settings detect this as a threat and block the request. Heatmap samples such as clicks and scrolls are much smaller requests and are generally treated as normal requests.


With the web console in the Browser Developer Tools (F12) already open, visit the page in your website that you have configured for the heatmap. Check for any failed requests – these could be HTTP errors like 500, 403 or 414. If you do see any of these codes please check the following:

  • Web Application firewall settings.
  • Any security plugins, such as WordFence.
  • Your server POST request size limit may need increasing.
  • Check your server logs for a clearer description of the error.
  • Whitelist the Matomo requests so they aren’t blocked.

If you see a 414 error, it likely means the POST request was blocked by your website security settings. This is because the tracker will automatically attempt to send a GET request if the POST request fails. As the GET request will likely exceed the maximum URL character limit, a 414 error (URL too long) will occur.

If you are confident that your Matomo web server configuration is not the cause of the issue please create a trial on our Matomo cloud platform then use our dual tracking script (setting the cloud as the primary tracking endpoint).
Configure your heatmap with the same settings in the Matomo cloud instance and try again. If the cloud heatmap capture is successful, then it indicates that your Matomo server is blocking the requests.

How do I disable only session recording feature?

Heatmap and Session Recording features are bundled together and you may be wondering how to disable the Session Recording feature only. Luckily, there is a way to disable Session Recording alone with a single setting.

Things to consider:

  • Disabling Session Recording would be applied across all the websites added in Matomo
  • All the existing recordings will be deleted across all the websites
  • Heatmaps will be unaffected

Please follow the steps below to disable session recording:

  1. Login to Matomo as Super User
  2. Click on “Administration (cog icon on the top right)”
  3. Click on “Settings > General Settings”
  4. Scroll down to “HeatmapSessionRecording”
  5. Click on “Disable Session recording” check box
  6. Save

How to enable Session Recording again?
To enable Session recording again, follow the same steps as mentioned above.

How to prevent super users from enabling this feature again ?
It is possible that a Super User may accidentally enable the feature again. In order to prevent this from happening, below setting could be added to the config/config.ini.php. Once the setting is added to the config.ini.php file, the option to Disable/Enable Session Recording will not be available in the user interface anymore. If you’re using Matomo Cloud, you may have to get in touch with our Cloud Support team.


How does Heatmap and Session Recording track moves on a touch screen device?

To track moves of a user on screen Matomo adds 2 event listeners i.e mousemove and touchmove.

The mousemove event occurs when the pointer is moving while it is over an element.

The touchmove event occurs when the user moves the finger across the screen.

Note: The touchmove event will only work on devices with a touch screen.

How do I fix CORS issue for Heatmap and Session Recording

When a heatmap or session is being recorded, Matomo tries to save a webpage’s CSS (Cascading Style Sheets define the design of your website) along with the content of a webpage to ensure the page is still displayed correctly even if the CSS or the URLs to your CSS change.

For this feature to work, Matomo tries to read the CSS. If it can’t read the CSS from the DOM, then it tries to fetch the content using an extra HTTP request. This will work in most cases. However, in some cases, for example when you load your CSS from a CDN, then extra steps are needed.

If your heatmap or session recording displays correctly after taking the screenshot or recording, but doesn’t look good anymore after a while, then this might be causing the problem.

To fix this error, follow these steps:

  • Recommended: For Matomo to not having to make an additional HTTP request to fetch the CSS, set a crossorigin attribute on your link tag to anonymous. This will make it a lot faster for Matomo to get the CSS content. Example:
<link rel="stylesheet" href="{PATH_TO_YOUR_CSS_FILE}" crossorigin="anonymous">
  • Ensure a header is set Access-Control-Allow-Origin: {YOUR_DOMAIN} when your webpages are being requested. This will allow Matomo to load the CSS using an HTTP request. Example: If https://www.example.com is your Matomo tracking domain, then you need to set the header as Access-Control-Allow-Origin: https://www.example.com. To change this header, ask your system administrator or your hoster for help if needed. The header needs to be only set for CSS files.