Session recordings — Heatlens 1.1.0

1. Installation and preflight
2. Campaigns and playback
3. Consent and SPA navigation
4. Selective field opt-in
5. Retention and operations
6. Limits and troubleshooting
7. Visit navigation, context and sharing
8. Reader navigation

Heatlens 1.1.0 combines heatmaps and replay in one Matomo 5 plugin. Rendering has explicit limits; exhaustive parity is not claimed. See platform compatibility.

Installation and preflight

Use the archive matching your Matomo major: 1.x for Matomo 5.14.1–5.x, 2.x for Matomo 6 beta. PHP 8.1 or later, the native HTTP tracker and the bundled Heartbeat plugin (activated) are required. Replacing the native tracking handler with an external queue is unsupported: replay will not acknowledge storage it cannot confirm.

Back up the complete database, configuration and plugin, and verify restoration on a separate instance. Install into plugins/Heatlens with the web user's permissions, then run:

php console core:update --yes
php console custom-piwik-js:update
php console cache:clear

The migration adds five replay tables: campaigns, pages, chunks, temporary erasure markers and notification receipts. Existing heatmaps are not converted into replays. Capture starts only after campaign activation and consent. Start with synthetic content. Rollback requires a consistent database/file backup; do not uninstall to downgrade.

Allow encoded POST bodies up to 2 MiB at matomo.php, without redirects or caching. The tracker endpoint must not have a query, fragment or embedded credentials. Allow scripts under plugins/Heatlens/javascripts/replay/ and connections to your Matomo in the site's CSP. Behind a proxy, HeatlensReplay.setConfigurationUrl may specify that installation's index.php; modules load from its directory. No third-party CDN serves replay modules.

Disable tracker debug and HTTP request-body logging. Heatlens avoids journal payloads in its own errors and URLs; it cannot control operator/proxy logs.

Campaigns and playback

A site administrator creates a campaign under Session recordings: name, description, URL/path/query and country targeting, sampling, page quota, minimum duration, activity requirement, retention and repeat delay. Write-only access cannot manage replays. Authenticated viewers may read recordings; anonymous access stays forbidden even when the Matomo site is public.

Sampling is stable per native visit and campaign, from 0.1% to 100% in 0.1% steps. Quota counts committed pages, including later-erased pages; admission alone consumes nothing. The activity condition requires both a click and a scroll after the minimum duration. Until then the initial journal stays only in RAM and may be discarded. Activity and query-string targeting are evaluated in the browser.

Pause, resume, permanent end, cross-site copying (admin access required on both sites) and deletion are available. Editing or pausing immediately invalidates server capabilities; the browser checks every 30 seconds and stops after 45 seconds without fresh configuration. Without fresh configuration it stops within 45 seconds. Copy an ended campaign to record again. Automatic repeat creates one new campaign after the configured delay. The site cap is 100 retained campaigns; remove unneeded campaigns to allow further repeats.

Reports use native date/segment filters plus device, duration and recording state. Page and visit counts are separate. The Visit button selects that visit's pages; player Previous/Next follows that visit and campaign, beyond the current 50-row result page. Visitor-log links open available replays. Playback supports pause, speed, seeking, idle skipping and per-page JSON export. Transmission gaps remain visible; playback resumes at a valid checkpoint.

Replay completion emails have their own opt-in preference. Recipients must still have access to the site. Links require Matomo authentication and contain neither access tokens nor visitor data.

Consent and SPA navigation

Native tracking consent and opt-out take precedence. With requireConsent, setConsentGiven or rememberConsentGiven allows recording after the native pageview. Without native required consent, explicitly authorize replay:

_paq.push(['HeatlensReplay.setConsentGiven']);
// Revoke:
_paq.push(['HeatlensReplay.forgetConsentGiven']);

Revocation stops capture/transmission, clears RAM and aborts in-flight requests where still possible. Matomo's revocation marker is checked across tabs too. Previously stored recordings require explicit erasure through Matomo/Heatlens. No persistent local journal is kept.

For SPAs, keep native setCustomUrl + trackPageView on navigation. Heatlens ends the preceding journal and attaches the next one to the native visit; it does not manufacture a visit after expiry. Navigation detection is not a substitute for native pageview tracking. BFCache restoration starts a fresh journal. The final beacon is best effort; interrupted recordings are possible when completion was not acknowledged.

Selective field opt-in

All fields and values are masked by default. Enable selective capture on the campaign, list the allowed key, then mark the corresponding field, for example query:

<input type="search" data-heatlens-field="query" autocomplete="off">

The marker alone is insufficient. Ancestor data-heatlens-mask, data-matomo-mask, data-matomo-ignore and contenteditable masks always win. Allowed types are text, search, textarea, select, checkbox and radio. Passwords, hidden/file/contact/payment/authentication fields and sensitive types, autocomplete values, keys, attributes or labels remain excluded. Raw keystrokes are never recorded. Allowed field states are sampled on changes/checkpoints; email-like strings and runs of four or more digits are redacted. This is not a universal personal-data detector: only mark fields whose recording you intend and have assessed.

Retention and operations

Retention is 1–365 days, shortened by stricter native log retention. Existing Heatlens purge (daily) and processLifecycle (hourly) tasks also handle replay. The Matomo operator runs scheduled tasks and configures email; the plugin vendor does not host the customer's instance.

Deleting a page, campaign, site or visit erases its chunks. Temporary markers prevent delayed chunks from resurrecting erased recordings until their capabilities expire. Erasure does not replenish quota. PrivacyManager export includes replay with an explicit memory ceiling. For larger visits use heatlens:export-visit as described in the advanced guide: recordings and replaySummary supplement the existing heatmap format. Keep export files outside the web root.

Limits and troubleshooting

• Per page: 10 minutes, 8 MiB, 20,000 events and 1,000 chunks. Each checkpoint: at most 5,000 nodes and depth 40.
• In-memory queue: 1 MiB/64 chunks, at most five attempts, two-minute expiry. Limits stop capture instead of silently removing a middle chunk.
• Only a safe computed-style subset is replayed. Images, canvas, SVG, video, iframes and shadow DOM are not faithfully reproduced; sensitive/active elements are masked or omitted. Remote fonts, pseudo-elements and complete animations are unsupported. Original scripts, forms and links never execute in the player.
• No retroactive capture or reconstruction of lost events. The reader loads one bounded page rather than an entire visit into memory.

For an empty report check period/segment, targeting, consent, minimum duration, click + scroll, quota, status and sampling first. Then verify Heartbeat, matomo.js/modules and POST JSON acknowledgements in the browser Network panel. HTTP 2xx without a typed acknowledgement does not prove storage. Native tracking blocks, missing/expired visits and incompatible handlers can deny admission.

Matomo.getAsyncTracker().HeatlensReplay.getDiagnostics()

Diagnostics contain only a status (waiting, buffering, recording, sampled-out, admission-failed, policy-changed, configuration-unavailable, configuration-expired or limit), campaign count and queue size, never field values or tokens. Regenerate matomo.js and clear Matomo caches after updating the plugin.

Visit navigation, context and sharing

The optional autoplay control continues to the next page of the same visit and campaign. Dates use the site timezone. Each report row shows device, native browser, screen resolution, country and event count; unavailable native context is omitted after log purging. Previous/next works beyond the current 50-row result page.

Share generates an authenticated link to the selected recording. It may be used as an iframe source subject to the instance’s framing and cookie settings. No token is included; every read still requires site access, and the embedded view hides management controls. Native visitor links are hidden when visitor profiles are disabled.

In a filtered visit, Delete visit recordings removes its pages from every replay campaign after confirmation. Native Matomo visit data and heatmaps are kept. The public Heatlens.deleteReplayVisit(idSite, idVisit) API requires a secure POST and site administrator access.

Country targeting uses lowercase two-letter codes and is enforced against native Matomo geolocation on admission and append; an unknown country cannot match a restricted campaign. The 1 MiB/64-batch RAM limit applies per campaign.

Keyboard: Tab moves through controls, Space activates buttons and checkboxes, and arrow keys move the focused time slider.

Reader navigation

Reports group matching pages by visit, showing entry, exit and cumulative duration. Quotas still count pages. Open a visit to inspect its pages, or play a recording in the dedicated reader. Returning preserves report filters and pagination. The Details panel contains available metadata, playback options, sharing and export; it starts collapsed on small screens.

The page selector shows position within the visit and loads at most 50 choices. Previous (50)/Next (50) browse additional windows. Visit navigation includes all pages in that campaign, even outside the report filters. Timeline markers distinguish clicks, movement, scrolling, forms, resizing and DOM changes. Each marker groups one event category per second; its tooltip shows the count. Previous/next activity buttons provide keyboard navigation.

Outside editable controls: J/L seek by 10 seconds, K or space toggles playback, N opens the next page, A toggles autoplay, B toggles idle skipping, S changes speed. Typing and native control activation retain their usual behavior.

New recordings preserve masked control shapes using a fixed placeholder, without private values, text lengths or checked states. Older recordings retain their original appearance. Diagnostics include starts and lastStart without URLs or values. An expired policy stops capture; recovery does not automatically admit another page. Navigation or an explicit restart after checking consent can restart collection.

CSS fidelity

Replay stores computed styles: the source browser evaluates layers and variables. Hover, focus, font loading and stylesheet DOM mutations now schedule a capture after 100 ms. Vertical writing, direction, shadows and additional typography are retained. Very short transitions may be sampled; continuous animation or insertRule() without a DOM mutation is not captured frame by frame. Remote fonts are not embedded: a detected load updates metrics but does not guarantee font availability on the viewing device. Privacy controls and budgets still apply.

“View pages in this visit” opens a list headed with the visit number and page count; visit numbers become plain text in that view. “All visits” returns to the grouped list.

The event strip is the only seek control: click or drag with a mouse or touch. Focus it with Tab, then use arrows for 1-second steps (Shift: 10 seconds), Page Up/Down for 10 seconds and Home/End for either endpoint. Activity buttons seek precisely to the previous or next marker.

The report play button opens the page and starts playback from zero. Idle skipping is off by default. The player toggles between play and pause; play restarts from zero after the end. A zero-duration page remains viewable, with playback disabled.

The Actions panel is collapsed by default and lists all events chronologically with millisecond timestamps, types and available details (target, coordinates or dimensions). Its height is bounded and entries load progressively while scrolling. Clicking an entry seeks to its event and pauses playback. Field values are not included in the list.