# Session replay

Watch a sample of real sessions back: every click, scroll and page, and the moment a visitor got stuck or hit an error. Off by default until you turn it on for a data stream.

## What this report gives you

A heatmap tells you where people clicked on a page, all together. Session replay, at `/replay`, shows you one person: from the first page to the last, with mouse movement, scrolling, clicks that did nothing and the errors they saw. When a number in a report looks wrong, watch a few sessions to see what is behind it.

It sits in the sidebar under the Explore group, next to Heatmaps. It is two clicks from the menu to watching: open the list, click a session.

> **Plan-gated**
>
> Session replay depends on the website's plan, like Heatmaps. If the active website's plan does not include it, you see the upgrade card instead of the list. See [Plans and entitlements](analytics/admin/plans-and-entitlements).

A session is made of one or more **recordings**: each page load in each browser tab is one recording. A session that viewed three pages has three recordings, played back to back.

## Turn recording on

Recording adds a JavaScript module to your site's pages, so it is off by default and is turned on per data stream.

1. Open **Admin** in the console.
2. Under **Website settings**, go to **Data streams** and open the data stream.
3. Click the **Session replay** row.
4. Turn on Record sessions, set the options and click **Save**.

Recording starts from the next page load; a page that is already open is not recorded.

| Setting | What it means |
| --- | --- |
| Record sessions | This data stream's main switch. Off by default. |
| Sample rate | The share of sessions recorded, from 1 to 100%. The default is 10%. The draw is made per visitor, so a session is recorded whole or not at all. |
| Mask all page text | Masks every word on the page, not only email addresses. Use it for apps that show personal data. |
| Hide elements | One CSS selector per line, up to 20. A matching element is recorded as an empty box of the same size. |
| Capture JavaScript errors | Shows the page's errors on the timeline. On by default. Messages are cut to 200 characters with emails masked. |
| Longest recording (minutes) | A session stops recording after this long. The default and the maximum are 120. |
| Run until | An auto-stop date. Set it for a time-boxed study; leave it blank to run open-ended. |
| Exclude paths | One path prefix per line. Pages under these are not recorded. If a visitor in a single-page app navigates into such a path, the recording ends there and its unsent part is not sent either. |

![Session replay settings on a data stream.](https://docs.adpix.io/shots/analytics/explore/session-replay/settings.en.5963534150.png)
> Session replay settings on a data stream. — [analytics.adpix.io/en/admin?sel=data-streams](https://analytics.adpix.io/en/admin?sel=data-streams)

> **Start with a low rate**
>
> Every recorded session takes storage, and the website may have a monthly quota. On a busy site, start with a few percent, and for a specific investigation set Run until so recording ends on its own.

## The sessions list

`/replay` opens on the recorded sessions, newest first, 25 at a time. Load more adds the next batch. The window is the date picker at the top of the page.

Above the list are five chips: All, Rage clicks, Errors, Dead clicks and Converted. Each keeps only the sessions that contain that thing; Converted means the session contains one of the website's key events.

Below the chips are the filters:

- **Page** — type a path such as `/pricing` and press Enter. Sessions that viewed that page stay, wherever in the session it was.
- **Channel**, **country** and **device** — All channels, All countries, All devices, or one value.
- **Duration** — Any length, Over 30 seconds, Over 1 minute, Over 5 minutes.

Filters live in the page URL, so you can send a filtered list to a colleague. The player keeps the same filters.

Each row shows:

| Column | What |
| --- | --- |
| Dot | A filled dot means Not watched yet. This is kept in your browser only. |
| ID | The last few characters of the visitor's ID, or Anonymous. |
| Start and length | When the session started and how long it ran. |
| Pages and clicks | The session's page and click counts. |
| Context | Country, browser and device. |
| Badges | The number of rage clicks, errors and dead clicks. A badge that would be zero is not shown. |
| First page | The path the session started on. |

![The recorded sessions list with its chips, filters and rage-click and error badges.](https://docs.adpix.io/shots/analytics/explore/session-replay/list.en.0f5eec8d33.png)
> The recorded sessions list with its chips, filters and rage-click and error badges. — [analytics.adpix.io/en/replay](https://analytics.adpix.io/en/replay)

Below the list, a line says what share of sessions is being recorded. The list and its badges read summary data only and never open a recording, so they stay fast with thousands of sessions.

### When the list is empty

| Message | Meaning | What to do |
| --- | --- | --- |
| Session replay is off for this website | No data stream of this website records. | Click Open data stream settings and turn recording on. |
| Sessions appear here once visitors are sampled | Recording is on, but no session has been recorded in this window yet. The recording rate is in the message. | Wait, or widen the date range. |
| No sessions match these filters. | The filters exclude everything. | Click Clear filters. |

If the website reaches its monthly recording quota, a banner above the list says new sessions aren't recorded until next month. Sessions already recorded stay.

## The player

Clicking a row opens the session at `/replay/<id>`. It is a full page, so you can keep or share its address.

Across the top: the ← Sessions button back to the list, the visitor ID, the start time, the length, and the country, browser, OS, device and channel. ‹ Newer and Older › open the previous and next session with the same filters.

If the session has more than one recording, a Tab button with each page's path appears above the stage; clicking one jumps to the start of that recording. A tab that was open at the same time as another one (its button has a dashed border) is not mixed into the same playback: click it to watch that tab on its own, and click any other tab to go back. Below it, the URL bar shows the page the visitor was on at that moment.

Playback does not wait for the whole session to download. As soon as the first part arrives the first frame shows, and the rest is added while it plays. Until everything has arrived, Loading recording… with a part count shows below the controls.

Click the timeline under the stage to jump to that moment. It carries markers: blue for a page change, red for a rage click, dark grey for a dead click and orange for an error.

| Control | What it does |
| --- | --- |
| Play / Pause | Starts or stops playback. |
| `−10s` / `+10s` | Ten seconds back or forward. |
| Speed | 0.5× to 8×. Your choice is kept for next time. |
| Skip inactivity | Fast-forwards through stretches where the visitor did nothing. On by default. |
| Autoplay next | When this session ends, opens the next older one with the same filters and starts playing it. Off by default. |
| Copy link at this time | Copies an address with `?t=` and the second, and the website. Whoever opens it sees the session at that moment, even if their website switcher is on another website. |
| Open heatmap | Opens the heatmap of the page that is playing now. |

The Activity column beside the stage is the session's timed list of events: Page, Click, Rage click, Dead click and Error, with the element's label or the error text. Click a row to jump playback to that moment. Events you have not reached yet are dimmed.

![The player: the stage, the marked timeline, the controls and the Activity column.](https://docs.adpix.io/shots/analytics/explore/session-replay/player.en.855020fbec.png)
> The player: the stage, the marked timeline, the controls and the Activity column. — [analytics.adpix.io/en/replay](https://analytics.adpix.io/en/replay)

If the player says This recording stopped early, the session hit its length or size limit and the rest was not recorded. If the session has expired or been deleted, the player is replaced by This session is not available.

### Keyboard shortcuts

| Key | Action |
| --- | --- |
| `Space` | Play / pause |
| `←` / `→` | Back / forward 10 s |
| `↑` / `↓` | Faster / slower |
| `?` | Show these shortcuts (`Esc` closes them) |

## From a heatmap to sessions and back

The two pages are one click apart. On [Heatmaps](analytics/explore/heatmaps), once a page is selected, the Watch sessions button opens the list of sessions that viewed that page. In the player, Open heatmap takes you to the heatmap of the page you are watching.

## Privacy and consent

- **Inputs are always masked.** No input value is recorded, and this cannot be turned off.
- **Email addresses in page text are masked**, and so are those in attributes such as a `mailto:` link.
- **Mask all page text** masks every word on the page. To mask only one part, give that element the `data-adpix-mask` attribute.
- **Hide elements** leaves an element out entirely; only an empty space of the same size remains.
- Masking happens in the visitor's browser, before sending. What is masked never reaches AdPix and cannot be revealed later.
- `<canvas>` content is not recorded.

Recording is in the Statistics consent category, like heatmaps. If the cookie banner is on for the website, the recording module **does not load at all** until the visitor accepts Statistics. See [consent categories](analytics/privacy/consent-categories-and-gating).

The ID you see in the list and the player depends on your permissions: if your role may see user identifiers, you see the tail of the user ID that ties the visitor's devices together, otherwise only the tail of the device ID. No email or name appears on these pages.

## Limits and retention

| Limit | Value | Effect |
| --- | --- | --- |
| Length per session | Longest recording, at most 120 minutes | Recording stops and the session is marked as stopped early |
| Size per session | 8 MB | Same |
| Retention | 30 days by default | The nightly prune removes an expired session's recording first, then its rows |
| Website monthly quota | No quota by default | Once reached, recording stops until next month and a banner shows above the list |
| Platform sample-rate cap | No cap by default | Your data stream's rate is lowered to the cap |

The length and size limits count the whole session, not each page. Retention, the quota and the rate cap are set by the platform operator. If recording is turned off for all websites, new recordings stop within a minute.

> **Stopping does not break your site**
>
> When the quota runs out or the platform turns recording off, recording stops silently and the visitor sees no error. On your side, new sessions simply stop arriving. Before you look for a bug, check the sample rate, the Run until date and the quota banner.

## Frequently asked questions

### I turned recording on but the list is empty. Why?

Recording starts only for visitors who are sampled in, and only from their next page load. If the cookie banner is on, nothing is recorded until the visitor accepts the Statistics category. Excluded paths, a past Run until date and a website that reached its monthly quota also stop recording. Check the date range at the top of the page too.

### Is text a visitor types into a form recorded?

No. Every input value is always masked, and email addresses in page text are masked in the browser before anything is sent. For pages that show personal data, turn on Mask all page text or Hide elements.

### Why did a recording stop partway through a session?

Every session has limits: Longest recording (at most 120 minutes) and 8 MB of data. Reaching either stops the recording cleanly, and the player says above the stage that the recording stopped early.

### How long are recordings kept?

30 days by default. A nightly prune removes an expired session's recording first, then its rows. The platform operator can change the number.

## Related

- [Heatmaps](https://docs.adpix.io/en/analytics/explore/heatmaps/)
- [Data streams](https://docs.adpix.io/en/analytics/collect/data-streams/)
- [How consent is enforced in the tracker](https://docs.adpix.io/en/analytics/privacy/consent-categories-and-gating/)
- [Plans and entitlements](https://docs.adpix.io/en/analytics/admin/plans-and-entitlements/)

---

[Docs](https://docs.adpix.io/en/analytics/explore/session-replay/) · AdPix