> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hacktionbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Replay

> Record and replay user sessions for debugging.

### Recording modes

The replay system operates in three modes:

| Mode          | Description                                                                       |
| ------------- | --------------------------------------------------------------------------------- |
| **OFF**       | Replay is disabled or not started                                                 |
| **BUFFER**    | rrweb captures events into a ring buffer (\~30 seconds). Nothing is uploaded yet. |
| **RECORDING** | The buffer is flushed and new events are continuously uploaded in batches.        |

### Trigger events

Replay transitions from BUFFER to RECORDING when one of these events occurs:

* **Error** — an unhandled JavaScript error or `console.error` call
* **Widget open** — the user opens the chat widget

This approach minimizes bandwidth — most sessions stay in buffer mode and never upload data.

## Enabling replay

Session replay is controlled from the dashboard under **Settings → Widget → Features**. When enabled, the SDK automatically starts recording in buffer mode on initialization.

No code changes are needed — the SDK reads the `sessionReplay` flag from your widget configuration.

## Data handling

* Batches are **gzipped** using the browser's native `CompressionStream` API before upload
* Uploads use **widget JWT authentication** (obtained during the widget auth handshake)
* Batches include a sequence number for ordered playback
* If the upload quota is exceeded (HTTP 402/429), recording stops automatically

## Privacy & masking

The SDK applies these privacy defaults:

| Setting                    | Value                                                           |
| -------------------------- | --------------------------------------------------------------- |
| `maskAllInputs`            | `true` — all input values are masked                            |
| `maskTextSelector`         | `[data-hb-mask]` — add this attribute to mask specific text     |
| `blockSelector`            | Widget elements and `[data-hb-block]` — excluded from recording |
| `recordCanvas`             | `false` — canvas elements are not recorded                      |
| `recordCrossOriginIframes` | `false` — cross-origin iframes are skipped                      |
| `inlineImages`             | `false` — images are referenced by URL, not inlined             |

### Masking specific elements

Add `data-hb-mask` to mask text content:

```html theme={null}
<p data-hb-mask>This text will be masked in replays</p>
```

Add `data-hb-block` to exclude an element entirely:

```html theme={null}
<div data-hb-block>This element won't appear in replays</div>
```

## GDPR opt-out

Call `disableReplay()` to permanently stop session replay for the current user:

```javascript theme={null}
Hacktionbase.disableReplay();
```

This immediately stops rrweb recording, clears the buffer, and prevents replay from restarting — even on page reload (until `destroy()` + `init()` is called again).

Use this to honor user privacy preferences or implement a "Do not record" toggle in your application.