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.

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.
• Visual proof can mislead if traffic/device mix differs between variants.