Skip to content

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 } }
SettingWhat it does
replayTurns on session recording.
replay_shareThe share of sessions to record, from 0.01 to 1. 0.1 by default.
mask_all_textMasks all text and media as well, not only inputs.

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 load event 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 value attributes.
  • 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-label and aria-description.
  • Images, video, audio, canvas, picture, svg, iframes, object and embed are 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

AttributeEffect
data-nl-maskMasks the text and inputs inside the element.
data-nl-blockBlocks the element, showing an empty box of the same size.
data-nl-unmaskWith mask_all_text on, shows the element's text, media and ordinary inputs.
<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:

  • replays lists 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.
  • replay returns 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}/recordings lists recorded sessions.
  • GET https://api.nanolytics.dev/v1/sites/{site}/recordings/{id}/session?date=YYYY-MM-DD returns one session's events in order.
  • GET https://api.nanolytics.dev/v1/sites/{site}/recordings/{id}?date=YYYY-MM-DD returns 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.