Blank Heatmaps in Matomo

Sometimes you may encounter blank areas or entirely empty heatmaps while using the heatmap feature of Matomo. The following are some of the common issues that may cause blank heatmaps and the steps you can take to resolve them.

HTTP/HTTPS Issues

Blank heatmaps can occur due to HTTP/HTTPS configuration issues. Make sure that your website is accessible via the chosen protocol (HTTP or HTTPS) and that the URL specified in your heatmap is the protocol used on your website.

It’s important to note Matomo’s URL configuration for heatmaps, the « equals simple » option and the « equals exactly » option define how Matomo matches URLs. When you choose « equals simple, » the protocol (HTTP or HTTPS), any URL parameter, and trailing slashes in a path are ignored. This allows you to more easily match different versions of a page URL. On the contrary, when selecting « equals exactly, » the URL value has to match exactly, including the protocol, URL parameters, and trailing slashes.

The following page covers the various rules you can configure to define which pages this feature should be activated on. What do the different rule types mean?

CORS (Cross-Origin Resource Sharing) Issues

Blank heatmaps can result from CORS-related problems. When viewing the heatmap, you might encounter an error in the browsers web console: « blocked by CORS policy: No ‘Access-Control-Allow-Origin’ header is present on the requested resource. » This error indicates that the Matomo tracking code is unable to access resources on your website due to CORS restrictions.

When you see the CORS error in the browser console, the solution is to configure your website to enable Cross-Origin Resource Sharing (CORS). This involves adding an ‘Access-Control-Allow-Origin: *’ HTTP header in your website’s responses. This header grants permission for Matomo’s domains to access your website’s resources, allowing the heatmap data to be retrieved and displayed properly. To implement this solution, you may need to contact your webmaster or your technical team for assistance in configuring CORS settings on your server.

During heatmap or session recording, Matomo captures a webpage’s CSS (Cascading Style Sheets, which define a website’s design) and its content. This ensures proper display even if CSS or CSS URLs change.

Matomo first attempts to read CSS from the DOM (Document Object Model). If this fails, it fetches content via an extra HTTP request, usually successful. Yet, situations like loading CSS from a CDN may require additional steps.

To solve this issue, we suggest setting a crossorigin attribute on your link tag to anonymous.
Example:

<link rel="stylesheet" href="{PATH_TO_YOUR_CSS_FILE}" crossorigin="anonymous">

Also 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.

Reference: Cross-origin resource sharing.

100% Element Height Issue

The 100% element height issue refers to situations where elements on a webpage have a height defined as 100%, potentially causing conflicts with heatmap rendering. This can lead to blank areas on the heatmap.

To solve this issue, we suggest setting 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.

Missing CSS Formatting

Your heatmap might be recording but fail to display accurately if the necessary CSS (Cascading Style Sheets) files required for proper styling are missing. This can result in improperly rendered or incomplete heatmaps.

If your heatmap is not displaying as expected, check the web browser console for errors indicating missing CSS files. These errors could point to specific resources that are required for heatmap rendering.

This can usually be solved by:

Replace Missing CSS Files: Manually ensure that the missing CSS files are present in the directory where Matomo is searching for them. This action provides the necessary styling information for accurate heatmap rendering.

Regenerate the Heatmap: If the missing CSS files have been restored or no changes were made to the page’s structure, consider deleting the existing heatmap screenshot in Matomo. Matomo will then regenerate a new screenshot that includes the now-available CSS.