Skip to content
bucker

Heatmaps

DX-14. Where people click and how far they scroll on one route, read from the counters the interaction stream already folds. Bucker keeps no page, no raw click and no session for this: a heatmap is a ranked table of elements, a scroll-reach curve and, once a person allows it, a coarse grid of click positions. The picture behind it is one you upload.

Nothing here works until product analytics is enabled for the project (the PA-01 gate). With the gate shut every heatmap route and tool refuses and stores nothing.

What a heatmap holds

Part Source Notes
Top 15 elements interaction_route_hours Clicks, share of the route's clicks, sessions, rage clicks, dead clicks, and clicks followed by an error within one second. Route-wide: the viewport filter does not split it.
Attribution the same totals.attributionRate is the share of clicks that name an element. A click the SDK could not name counts in the total and in no element.
other the cohort floor An element whose busiest single hour had fewer sessions than the project's minimum cohort size (default 5) is folded into other, with its clicks. The busiest hour is a lower bound on distinct sessions, so one visitor who clicks across five hours is not five people.
Positioned clicks per viewport heatmap_cells Only clicks that carried a position.
Scroll reach heatmap_cells (scroll cell) The share of sessions that scrolled at least to each 6.25 % step, and medianDepthPct, the depth by which half of the sessions had left (100 when most read to the end). Withheld when fewer sessions than the floor left the route.
Grid cells heatmap_cells Page-relative click counts on a 100 by 100 grid. Off until a person enables them, and cells under the cohort floor are dropped.
selector_check interaction_route_hours, last 7 days include: ["selector_check"] with a selector says whether its last element appears among the route's elements.

An element is the last part of its selector (button.primary). The whole chain is kept only as a digest, so two chains that end in the same leaf read as one element. Selectors and routes are text from your page: the MCP tool treats them as untrusted and says so in trust.untrustedFields.

Coordinates are opt-in

heatmap_capture.enable turns click coordinates on for a project. It is a human-only act: an organization OWNER, signed in as themselves, with a stated reason and the statement that a privacy review took place. No agent, service, OAuth client or personal access token can do it, whatever scopes it holds. The act is audited; enabling twice writes nothing. The setting is heatmapCoordinates on the project's web settings and is read fresh on every call; the SDK learns of it from the capture document's replay section.

There is no tool that enables it and none that disables it: turning it back off is not an act the registry knows yet.

Screenshots

Bucker does not render your page. To draw a heatmap over a picture, a person uploads a PNG or JPEG (heatmap_screenshot.create, human-only, org:admin).

  • The file is checked by content, not by the type it claims: PNG or JPEG magic, the size read from the header, at most 2 MiB and 8,000 by 30,000 pixels. Anything else is refused.
  • It is stored under heatmaps/<project id>/<sha256>.<ext> and deduplicated per route and viewport bucket. A project keeps at most 50.
  • It is served back only to a reader of that project, with nosniff and a sandboxing content-security-policy.
  • It is erased when the project or the organization is deleted, and after the lifetime you set (expiresInDays).

The overlay itself (the table, the image and the cells together) is drawn in the dashboard, in your browser. The live-page overlay is a later feature and is not part of this.

REST

Route Act
GET /orgs/:org/projects/:project/interactions/heatmap?route=&days=&viewport=&selector= read (analytics:read)
GET .../interactions/heatmap/screenshots?route= read
GET .../interactions/heatmap/screenshots/:id/image read
POST .../interactions/heatmap/screenshot heatmap_screenshot.create, human-only
POST .../interactions/heatmap/capture heatmap_capture.enable, human-only

MCP

heatmap_get (dx toolset, 800 tokens, 1,200 with a selector check). It reads under analytics:read, which is held: no token minted in production reaches it until the MCP ceiling is raised (SG-059). It writes one aggregated data.read count, because it returns no personal data.