Heatmap-lite
OConvert's heatmap is intentionally lightweight: it samples a fraction of clicks and stores percentage-based coordinates so it works across viewport sizes.
How clicks are captured
The runtime listens for click events on the document. For each click it computes:
x_pct- click x as a percentage of viewport widthy_pct- click y as a percentage of viewport heightvw,vh- the viewport dimensions at the time of the clicktarget- a short descriptor of the clicked element
The sample rate is controlled by the oconvert_heatmap_sample_rate filter (default 0.25, so one in four clicks is recorded). To capture everything, return 1.0 from the filter.
Ingest path
Clicks are POSTed to /wp-json/oconvert/v1/event with type='click'. The endpoint is public (no nonce required for anonymous tracking) but rate-limited per IP at 600 events per minute via a transient bucket.
Worker-friendly write
The DB write is deferred to a shutdown hook and the response is flushed early with fastcgi_finish_request() where available. This frees the PHP-FPM worker before the insert runs, which keeps the worker pool healthy on high-traffic sites.
Reading the data
OConvert_Events::heatmap_summary($page_url, $bins = 20) bins the most recent 5,000 clicks for the given page into a bins x bins grid. The admin UI at OConvert, Heatmap renders the grid as a tinted overlay.
The REST endpoint is:
GET /wp-json/oconvert/v1/heatmap?page_url=<url>It requires manage_options and returns { bins, grid, sample }.
Toggling
Disable the heatmap entirely with add_filter('oconvert_heatmap_enabled', '__return_false'). The runtime checks this flag in window.OCV.enabled.heatmap before binding the click listener.