Matomo Heatmap Requirements

Heatmaps in Matomo are a powerful feature that allows you to visually analyze user interactions and behaviors on your website. Heatmaps provide valuable insights by displaying aggregated data in the form of color-coded visualizations, making it easier to understand user engagement patterns.

To enable heatmaps in Matomo, you need to meet the following requirements.

JavaScript Tracking Code:

Heatmaps in Matomo require JavaScript to function properly. Ensure that you have correctly implemented the Matomo tracking code on your website pages. This tracking code is responsible for collecting user data, which is then used to generate the heatmaps. You can locate the tracking code for your websites from Administration > Websites > Tracking Code.

It’s important to note, if JavaScript cannot be incorporated, as is the case with iOS, Android, or desktop applications, heatmaps and session recordings will not function. Our current heatmap support is exclusively tailored for web browser tracking.

Accessible configs.php file:

Matomo relies on the configs.php file to store configuration settings. Ensure that this file is accessible and not blocked by any server-side restrictions or security measures. If the configs.php file is blocked, heatmaps and session recording may not work as expected.

Ensure that you comply with applicable data privacy regulations and obtain user consent if required before enabling heatmaps on your website. Respecting user privacy is crucial when using tracking tools like Matomo. The Matomo developer hub has instructions on how to mask private data in your recordings.

Working with iframes

Heatmaps with iframes can be a bit tricky, since the concept of an iframe is to not expose any of its internal HTML to the parent page to keep things secure. In general there are some options:

Add the tracking code to the iFrame itself – In some cases if you have access to the iframed page, you can try adding the tracking code to the iframed page. If doing this, it is important to first check the following faq – https://matomo.org/faq/how-to/how-do-i-track-a-website-within-an-iframe

Load the page content from the iFrame differently – An example would be using jQuery to get the content of the page and then insert specific page elements into the page they need to be displayed on.

If heatmaps are not working as expected, please consider the following troubleshooting steps.

Once you’ve completed your heatmap setup, you may want to read the Heatmap & Session Recording developer FAQ, or learn more about the Heatmap & Session Recording JavaScript API.

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