# 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`:

```json
{ "site": 42, "tracker": { "replay": true, "replay_share": 0.1 } }
```

| Setting | What it does |
|---|---|
| `replay` | Turns on session recording. |
| `replay_share` | The share of sessions to record, from `0.01` to `1`. `0.1` by default. |
| `mask_all_text` | Masks 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

| Attribute | Effect |
|---|---|
| `data-nl-mask` | Masks the text and inputs inside the element. |
| `data-nl-block` | Blocks the element, showing an empty box of the same size. |
| `data-nl-unmask` | With `mask_all_text` on, shows the element's text, media and ordinary inputs. |

```html
<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](/docs/errors).

The `replays` metric counts recorded sessions, so you can query it like any other metric. See [Query API](/docs/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](/docs/mcp).

## 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](/docs/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.
