Heatmaps, behavior screenshots, and visual evidence

Simple terms

Visual evidence helps explain what visitors saw or did, not just whether the metric moved.

Adds visual and behavioral proof to analytics so teams can understand not only whether a test moved a metric but how visitors interacted.

Routes

• /tests/[id]
• /analytics
• /api/analytics/experiment/[id]/heatmap
• /api/analytics/experiment/[id]/heatmap/screenshots
• /api/analytics/experiment/[id]/behavior
• /api/analytics/experiment/[id]/behavior-summary

Implementation behavior

• Behavior screenshots and heatmap endpoints store or query visual evidence tied to shop, page, experiment, variation, and time window.
• Experiment detail can combine screenshots, event data, and conversion metrics into a richer readback.
• Operator QA evidence can also include screenshots and observations gathered during preview.

How to use it

• Use visual evidence when conversion movement needs explanation.
• Compare control and treatment screenshots for obvious rendering differences.
• Use heatmap or behavior data alongside visitor trails rather than as the only decision source.
• Capture fresh evidence after variant changes.

Session replays

Replay-enabled experiments add a Session replays section to the results Behavior tab. The list excludes QA sessions by default and supports variation, device, conversion, and friction filters. Open a row to watch the masked recording without leaving the result.

Enable replay capture before launch. New recordings use the experiment's replay sample rate, so an enabled test can remain empty until a sampled visitor arrives. Input masking is applied before storage and cannot be removed in the player. Production recordings expire after 30 days.

Use rage clicks, dead clicks, error clicks, quick backs, form abandonment, and scroll depth to choose useful sessions. Replays explain a result. They do not select the winning variation.

When not to use it

• Do not use heatmaps as the sole decision source for an experiment winner.
• Do not compare screenshots captured before and after unrelated page/theme changes as if they are equivalent.
• Do not overread sparse heatmaps with low traffic.

Implementation source

• Experiment detail and analytics pages consume visual evidence APIs.
• Handlers include /api/analytics/experiment/[id]/heatmap, /api/analytics/experiment/[id]/heatmap/screenshots, /api/analytics/experiment/[id]/behavior, and /api/analytics/experiment/[id]/behavior-summary.
• Evidence is keyed by shop, page, experiment, variation, device, and time window where supported.

Data and API

• APIs under /api/analytics/experiment/[id]/heatmap, /api/analytics/experiment/[id]/heatmap/screenshots, /api/analytics/experiment/[id]/behavior, /api/analytics/experiment/[id]/behavior-summary, screenshot jobs, and operator evidence endpoints.
• Tinybird event streams plus persisted screenshot/evidence records.
• Experiment and variation IDs connect visual evidence to results.

Failure modes

• Missing screenshot: target page inaccessible, job failed, or evidence was captured before the variation rendered.
• Heatmap sparse: not enough traffic or events in the selected time window.
• Replay list empty: replay capture was off, no sampled visitor has arrived, or the retained recording has expired.
• Visual proof can mislead if traffic/device mix differs between variants.