How to capture the initial heatmap snapshot manually?

Cloud On-Premise

By default, Matomo automatically captures the heatmap snapshot the first time a page matching your heatmap is loaded.

You can enable the manual snapshot capture only when you need to control exactly when that snapshot is captured, for example:

  • Single page applications where content is rendered after JavaScript updates the page.
  • Pages that require user interaction before important content is displayed such as opening a menu.
  • Replacing an existing snapshot that captured an unwanted page state, such as a cookie banner or loading spinner.

Note: If you have excluded your IP address in Matomo (Websites or Global settings > Excluded IPs), manual snapshot capture will not work. Temporarily remove your IP address from the exclusion list before capturing a snapshot.

Capture a snapshot manually

  1. Create a new heatmap or edit an existing one.
  2. Ensure the setting is enabled, Capture Heatmap Snapshot Manually.
  3. Open the page in the exact state you want to use as the heatmap background.
  4. Run the command below from your browser’s Developer Tools console. Replace X with your heatmap id:
_paq.push(['HeatmapSessionRecording::captureInitialDom', X]);

Matomo captures the current page state and stores it as the heatmap background. Future heatmap recordings use this stored snapshot until it is replaced.

Delete and retake a snapshot

If the snapshot is outdated or does not represent the page correctly, you can delete it and take a new one. A new snapshot can be captured automatically or manually while the heatmap is still recording. Read more about how to delete and retake a heatmap snapshot.

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