Session replay
Session replay records a share of your visitors' sessions so you can watch how people actually used your site. Anything people type is masked in their browser before it's sent. This page covers turning replay on, sampling, masking, and viewing recordings.
Enabling session replay
Replay is a site setting. You can turn it on in Settings, from the Replays view, or with the MCP tool update_site:
{ "site": 42, "tracker": { "replay": true, "replay_share": 0.1 } }Changes reach visitors within five minutes, with no change to your code.
What gets recorded
Sampling
- Each session is recorded in full or not at all. Whether to record is decided once per session and stays the same as long as the visitor's page loads are less than 30 minutes apart.
- If you change
replay_share, it applies from each visitor's next page load. - Sessions aren't recorded when the browser sends a Global Privacy Control signal, when the visitor has withdrawn consent with
nl.consent(false), or when the browser is controlled by automation.
Performance
- The replay add-on is 2 KB gzipped at most. The recorder itself, up to 20 KB gzipped, is only downloaded on page loads that are being recorded.
- Recording starts after the page's
loadevent and a moment of idle time (2 seconds at most), so it never competes with your page's largest paint. - Events are sent in chunks every 30 seconds or at 512 KiB, and whenever the page is hidden.
- A recording stops after 4 hours or 50 MiB sent.
nl.consent(false)stops a recording immediately and discards anything that hasn't been sent.
What is never recorded
- Canvas contents and iframes.
- Console output and network requests.
- The query string and fragment of any URL. Recorded URLs keep only their origin and path.
Masking
Masking happens in the browser, so masked content never leaves it.
By default
- The value of every input, whether typed or set by script, is masked, along with
valueattributes. - Text, images and other attributes are visible.
With mask_all_text
- Every text node is replaced with
*s of the same length. - The same goes for
title,alt,placeholder,label,aria-labelandaria-description. - Images, video, audio, canvas,
picture,svg, iframes,objectandembedare blocked and shown as empty boxes of the same size.
Always hidden, whatever your settings
Password and hidden inputs, and inputs autocompleted as card numbers, card security codes, card expiry dates or one-time codes.
In your markup
<section data-nl-mask>
<p>Account number: 12345678</p>
</section>When both data-nl-mask and data-nl-unmask apply, the one on the closest ancestor wins. Neither crosses into a shadow root, so with mask_all_text on, content inside a shadow root stays masked unless it has its own data-nl-unmask.
There's no dashboard switch to unmask recordings. What's visible is decided by your pages' markup.
Viewing recordings
The Replays view lists recorded sessions in the dashboard's date range, newest first, with each one's start time, length, pages, country, browser and errors. The player steps through a session's page loads in order.
When an error happens on a recorded page load, it links to the replay, which opens just before the error. See Error tracking.
The replays metric counts recorded sessions, so you can query it like any other metric. See Query API.
From your agent
Your agent can find out what happened in a session without watching it:
replayslists recorded sessions, newest first, with each one's pages, duration, country, browser, errors and a link to watch it. It accepts the same filters as a query, so you can look for sessions on a page, from a country, in a browser, or with an error.replayreturns one session's events in order (pages, custom events, errors, engagement and page speed), each timed from the start of the session.
See MCP server.
From the API
GET https://api.nanolytics.dev/v1/sites/{site}/recordingslists recorded sessions.GET https://api.nanolytics.dev/v1/sites/{site}/recordings/{id}/session?date=YYYY-MM-DDreturns one session's events in order.GET https://api.nanolytics.dev/v1/sites/{site}/recordings/{id}?date=YYYY-MM-DDreturns one recording's rrweb events, gzipped and base64-encoded.
See Query API.
Storage
Each chunk is stored encrypted, under its own key that's kept only with that chunk's record. The server only reads a recording's contents to send it to the player.