heatmap

Invocation#

echo-cli heatmap page --app <web source> --path <page path> --since <iso-time> [--click-event <event> --element-property <property> [--position-property <property> --cells <n>]] [--scroll-event <event> --depth-property <property>] [--test <landing-test-id>]
echo-cli heatmap widget --app <web source> [--click-event <event> --element-property <property> [--position-property <property>]] [--scroll-event <event> --depth-property <property> --depths <percent,...>]

Inputs and output#

page writes app_id, path, since, cells (the grid's side, or null without --position-property), events (the click and scroll events read), unexposed (those of subjects the named test never showed) and variants: one per variant of the test, or one with variant null without a test, each with clicks (element and clicks, most first), positions (column, row and clicks for every grid cell someone clicked, counted from the page's top left, most first; empty without a grid), unplaced (the clicks whose position property held no { x, y } within 0 and 1) and scroll (depth and subjects, how many subjects' farthest depth reached it, by depth). widget writes script_url, snippet (the script tag carrying the web source, the subject the page fills in, and the events, properties and depth marks named) and script_bytes, the size of the script Echo Web serves now.

State effect#

page calls Echo Web's authenticated /api/analytics/heatmap with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; widget reads the public /api/public/heatmap/widget without a bearer. The Click and scroll maps section of the tracking screen and of Echo Desktop's GEO screen call the same operations (both print the collector), and echo-mcp reads maps as echo_page_heatmap and the collector as echo_heatmap_widget. page reads web_analytics_events of the web source, the page path as the client sent it and the event named, since the instant; it stores nothing. Echo names no click or scroll event of its own: the caller names the events the site's client sends and the properties carrying the element and the depth, and a click without the element property or a scroll without a numeric depth is left out. A subject is the event's user id when signed in, else its anonymous id; with --test, each is counted under the variant its stored landing exposure gave it. The collector, loaded in a page, posts to the public /api/analytics/web/collect: each click as the click event with the element clicked (its data-echo-element, else its tag, id and first class) in the element property, and each depth mark the visitor passes, once, as the scroll event with the mark in the depth property, the highest mark standing for the page's end; those events must be declared in the source's event contract. A page script naming neither pair or no subject sends nothing and says why in the console, as does a refused event.

Refusals#

• A wrong invocation is refused before anything is sent: "heatmap takes <every verb's usage, separated by semicolons>; got <word>", "heatmap page does not take <flag>; it takes …", "<flag> needs a value" and "heatmap page needs <flag>".
• Echo Web answers a bad request with "app_id is required: …", "path is required: …", "since is required: …", "since must be an ISO 8601 instant; got <value>", "click_event or scroll_event is required: the event the site's client sends for a click or for scrolling", "element_property is required: the property of a click event naming the element clicked" or "depth_property is required: the property of a scroll event holding how far the page was scrolled"; and not found with "landing test <id> has shown no subject a variant; echo-cli landing exposures --test <id> reads them". The command prints Echo Web's sentence and exits 1.
• widget is refused before anything is sent with "app_id is required: the web source whose page sends the events" and "name --click-event with --element-property, or --scroll-event with --depth-property and --depths, or both: the events the collector sends".
• With --position-property, page lays the clicks on a grid of --cells columns and rows over the page: a click at { x, y } (fractions of the page's full width and height, as the collector's data-position-property sends them from the click's page coordinates over the document's scroll size) counts in column floor(x × cells) and row floor(y × cells), the last column and row taking x or y of 1. Echo Web refuses "cells must be a whole number of at least 1 with position_property: how many columns and rows the grid laid over the page has; got <value>". The Click and scroll maps sections of the tracking screen and of Echo Desktop draw the grid, each cell shaded by its share of the most clicked cell.