# Session Replay
URL: https://pieowl.com/docs/session-replay
Session replay records what users do on your website. You can replay any session to see what they clicked, how they filled in forms, and where they got stuck, without guessing.
Session replay is **off by default**. You turn it on per site in the dashboard, with no code to edit. When it's off, the replay script is never downloaded, so your analytics script stays small.
How it works [#how-it-works]
Pieowl session replay is built on [rrweb](https://www.rrweb.io/), a widely used library for recording and replaying web sessions. It captures page changes, mouse movements, scroll positions and clicks as structured data, not video.
The recorder loads **asynchronously** as a separate script (`pieowl-replay.js`). This means:
* The main tracking script (`pieowl.js`) stays small, with or without replay
* The recorder is only downloaded for sessions that are actually recorded
* Page load speed isn't affected when replay is off
Retention [#retention]
Replays are kept for 30 days, then deleted automatically.
Setup [#setup]
1. [Install Pieowl](/docs/sdks/script). The one-line script tag or the `@pieowl/web` package is enough.
2. In the dashboard, open **Settings → Site → What Pieowl counts** and turn on **Session replay**.
3. Keep **Record only after visitors agree** on (it's on by default), and call `allowReplay` when a visitor accepts in your consent banner. See [Consent](#consent).
4. Choose **Visits recorded**: every visit, 50%, 25% or 10% of visits. Fewer recordings keep the list short on busy sites.
The script loads these settings on every page. A change reaches your site within about a minute. When replay is off for a site, Pieowl drops any recordings sent for it.
With the npm package, your bundler splits the recorder into its own chunk. It's never part of your main bundle, and it's only loaded when session replay is on.
Watching replays [#watching-replays]
Go to **People → Visitors → Visits**. Visits with a recording have a **Replay** chip. Open a visit and click **Watch replay**.
Options in code [#options-in-code]
Most sites need none of these. To use them, add `sessionReplay` to the [`init` form](/docs/sdks/script#options-in-code) or to `new Pieowl({...})`. They don't turn replay on; that's done in the dashboard.
| Option | Type | Default | Description |
| ------------------- | -------- | ---------------------------- | ------------------------------------------------------------ |
| `blockSelector` | `string` | `[data-pieowl-replay-block]` | CSS selector for elements to replace with a placeholder |
| `blockClass` | `string` | — | Class name that blocks elements from being recorded |
| `ignoreSelector` | `string` | — | CSS selector for elements whose interactions aren't recorded |
| `flushIntervalMs` | `number` | `10000` | How often (ms) recorded data is sent to the server |
| `maxEventsPerChunk` | `number` | `200` | Maximum number of recorded events per chunk |
| `maxPayloadBytes` | `number` | `1048576` | Maximum chunk size in bytes (1 MB) |
| `scriptUrl` | `string` | — | Custom URL for the replay script (script tag only) |
Privacy controls [#privacy-controls]
All text and form fields are always hidden. Each character is replaced with `*` in the browser, before anything is sent. Page text, labels and input values show up as `***` in replays, while the layout stays visible. This can't be turned off, in the dashboard or in code.
So replays can't capture names, emails or other personal data shown as text on the page. Images still show. To hide one, such as a photo of a face, block it.
Blocking elements [#blocking-elements]
Elements that match `blockSelector` or `blockClass` show up as a grey placeholder of the same size. The element and everything inside it are never recorded.
```html
This section won't appear in replays at all
```
Or use your own selector:
```ts
sessionReplay: {
blockSelector: '.payment-form, .user-avatar',
blockClass: 'no-replay',
}
```
Setting `blockSelector` replaces the default, so add `[data-pieowl-replay-block]` to your selector if you still want the attribute to work.
Ignoring interactions [#ignoring-interactions]
Use `ignoreSelector` to skip interactions on some elements. The element still shows in the replay, but clicks and typing on it aren't recorded.
```ts
sessionReplay: {
ignoreSelector: '.debug-panel',
}
```
Consent [#consent]
Recording visits needs your visitors' consent. Ask for it in your own consent banner, and name Pieowl session replay in your privacy policy.
With **Record only after visitors agree** on, Pieowl records nothing until your site calls `allowReplay` after the visitor accepts:
```js
// Script tag
window.pieowl('allowReplay');
// npm package
pieowl.allowReplay();
```
Pieowl stores nothing in the browser, so call it on every page where the visitor has agreed. If they decline, don't call it. See [Consent management](/docs/consent-management#session-replay-only-after-consent) and [Do you need a cookie banner?](/docs/consent-and-cookie-banners).
Custom script URL [#custom-script-url]
The script tag loads the recorder from next to `pieowl.js`: it swaps `.js` for `-replay.js` in the script URL. If you serve `pieowl.js` from your own domain, put `pieowl-replay.js` next to it. You can also set the URL yourself:
```ts
sessionReplay: {
scriptUrl: 'https://your-cdn.example.com/pieowl-replay.js',
}
```
Related [#related]
* [Session tracking](/features/session-tracking) — understand sessions without full replay
* [Session replay feature overview](/features/session-replay) — what you get with session replay
* [Web SDK](/docs/sdks/web) — full Web SDK reference
* [Script tag](/docs/sdks/script) — using Pieowl with a script tag