How can I share a heatmap?

To share a heatmap, you can embed it into an external HTML page. The method below uses the HeatmapSessionRecording API to generate the correct heatmap URL for you to add in an iframe.

Follow the steps below to ensure the heatmap loads with the right access and permissions.

Create a Matomo user with View access

1. Log in to Matomo as a Superuser and go to Administration > System > Users.
2. Create a new user and assign the View permission for the site that contains the heatmap you want to share.
3. Log out of Matomo.
4. Log in again as the new user and generate a new token_auth for this user.
5. Copy and store the token_auth value.

This will keep the shared heatmap secure as the iframe will use the token_auth from the View-only user.

Get the Heatmap iframe URL

Call the HeatmapSessionRecording.getHeatmaps API method to return the heatmapViewUrl for each heatmap, for example:

https://EXAMPLE.matomo.cloud/index.php //Replace with your Matomo domain.
?module=API
&method=HeatmapSessionRecording.getHeatmaps
&idSite=1 //Replace with your Matomo site ID.
&includePageTreeMirror=1
&format=xml
&token_auth=YOUR_TOKEN //Replace with the token_auth created by the View-only user.

From the generated report, copy the URL shown for <heatmapViewUrl>.

-<heatmapViewUrl>
https://EXAMPLE.matomo.cloud/index.php?module=Widgetize
&action=iframe
&moduleToWidgetize=HeatmapSessionRecording
&actionToWidgetize=showHeatmap
&idSiteHsr=HSR_ID
&useDateUrl=0
&idSite=SITE_ID
&period=day
&date=yesterday
&token_auth=YOUR_TOKEN
</heatmapViewUrl>

Embed the Heatmap in a custom page

Create a custom page on an external website and add the iframe that includes the heatmapViewUrl with the correct site URL and site ID, heatmap ID, and token_auth.

<iframe
  src="https://EXAMPLE.matomo.cloud/index.php?module=Widgetize&action=iframe&moduleToWidgetize=HeatmapSessionRecording&actionToWidgetize=showHeatmap&idSiteHsr=HSR_ID&useDateUrl=0&idSite=SITE_ID
&period=day&date=yesterday&token_auth=YOUR_TOKEN"
  width="100%"
  height="800"
  frameborder="0">
    </iframe>

• You will need to enable framed pages in your Matomo config file: enable_framed_pages = 1. Matomo Cloud users can request this setting change by contacting Support.
• Matomo blocks iframing by default for security reasons. This setting allows the heatmap to load inside an iframe on your external site.

After you enable framed pages and embed the iframe, the heatmap becomes accessible from any page, so you can share visual data with teams who do not need full Matomo access.