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

• /experiments/[id]/results?tab=behavior
• /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

Recent release notes

• The latest release normalises tap coordinates into the capture's frame and splits overlay and pinned (fixed) taps into separate fields; heatmap rollups now report category and element-level aggregations driven by the page model.

• Heatmaps: Show both versions at phone size on the real page picture, scroll them together, and list where sessions tapped by area. Harden capture recovery, partial session tables, and narrow-screen export availability.

• Cohort session counts used for arm denominators are now read from a single arm-sessions reader so every arm uses a consistent session denominator; when that read fails the arm is marked unavailable instead of returning zero.

• Field truncation and cells totals are tracked per row type (page, pinned, overlay) rather than being overwritten across types.

• Behavior screenshots and heatmap endpoints store or query visual evidence tied to shop, page, experiment, variation, and time window.

• The results Behavior tab combines heatmap data, behavior data, and conversion metrics in one readback.

• Note: retired "behavior explorer" landing links now redirect straight to an experiment's Results page and open the Behavior tab (previously they served an intermediate landing page).

• Operator QA evidence can also include screenshots and observations gathered during preview.

• Heatmaps: Raised the heat ramp transparency floor to keep page backgrounds clear between tap clusters.

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.