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

# Configuration

> Every SessionRecorder init option, with defaults, and the runtime API.

Pass a configuration object to `SessionRecorder.init()`. Only `apiKey` is required; every other option has a sensible default.

```ts theme={null}
import { SessionRecorder } from '@web-analytics-ai/obweb';

const recorder = await SessionRecorder.init({
  apiKey: 'ob_live_your_api_key_here',
  appVersion: '2.4.1',
  maskAllInputs: true,
  onReady: () => console.log('recording'),
  onError: (error) => console.error(error),
});
```

## Core options

| Option       | Type      | Default       | Description                                                                                                                                                                                                                                             |
| ------------ | --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`     | `string`  | required      | Your project API key. `ob_live_` keys record into the live environment, `ob_test_` keys into the test environment. The key and the page origin are validated together server-side.                                                                      |
| `appVersion` | `string`  | auto-detected | Release version to tag sessions with. If omitted, the SDK tries common conventions (framework build IDs, Sentry release globals, a `data-version` attribute on the script tag, a `<meta name="version">` tag). A warning is logged if nothing is found. |
| `region`     | `Region`  | `Region.US`   | Ingestion region. Only `US` is currently available; passing an unavailable region throws at init.                                                                                                                                                       |
| `debug`      | `boolean` | `false`       | Enables verbose SDK logging in the console.                                                                                                                                                                                                             |

## Privacy options

| Option             | Type      | Default           | Description                                                                                               |
| ------------------ | --------- | ----------------- | --------------------------------------------------------------------------------------------------------- |
| `maskAllInputs`    | `boolean` | `false`           | Mask the contents of every input field. Password, email, and tel inputs are masked even when this is off. |
| `maskTextClass`    | `string`  | `"replay-mask"`   | Elements with this class have their text masked.                                                          |
| `blockClass`       | `string`  | `"replay-block"`  | Elements with this class are not recorded at all (a placeholder of the same size is recorded instead).    |
| `ignoreClass`      | `string`  | `"replay-ignore"` | Input elements with this class have their input events ignored.                                           |
| `maskTextSelector` | `string`  | none              | CSS selector for additional elements whose text should be masked.                                         |
| `blockSelector`    | `string`  | none              | CSS selector for additional elements to block.                                                            |
| `ignoreSelector`   | `string`  | none              | CSS selector for additional inputs to ignore.                                                             |

See [Privacy and masking](/sdk/privacy-masking) for how these behave and what is covered by default.

## Delivery and session options

| Option              | Type      | Default   | Description                                                                                                              |
| ------------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `chunkSize`         | `number`  | `100`     | Maximum events per batch.                                                                                                |
| `flushInterval`     | `number`  | `15000`   | How often buffered events are flushed, in milliseconds.                                                                  |
| `maxChunkSizeBytes` | `number`  | `65536`   | Maximum batch payload size in bytes.                                                                                     |
| `maxIdleTime`       | `number`  | `1800000` | Idle window for a session, in milliseconds (30 minutes).                                                                 |
| `persistSession`    | `boolean` | `true`    | Continue the same session across page loads. When `false`, the session is ended on page unload.                          |
| `retryAttempts`     | `number`  | `3`       | Network retry attempts, with exponential backoff.                                                                        |
| `retryDelay`        | `number`  | `1000`    | Initial retry delay in milliseconds.                                                                                     |
| `timeout`           | `number`  | `30000`   | Network request timeout in milliseconds.                                                                                 |
| `recordOptions`     | `object`  | none      | Advanced escape hatch: overrides passed through to rrweb's `record()`. Use with care; incorrect values can break replay. |

## Callbacks

| Option           | Signature                     | Description                                                                  |
| ---------------- | ----------------------------- | ---------------------------------------------------------------------------- |
| `onReady`        | `() => void`                  | Fired when the SDK has finished initializing and the backend session exists. |
| `onSessionStart` | `(sessionId: string) => void` | Fired when a session starts.                                                 |
| `onChunkSent`    | `(chunk) => void`             | Fired after each event batch is sent.                                        |
| `onError`        | `(error) => void`             | Fired on SDK errors. Each error has a `code`, `message`, and `timestamp`.    |

## Runtime API

The recorder instance returned by `init()` exposes a small runtime API.

### `identify(userId, traits?)`

Attach your own user ID and traits to the current session. See [Identifying users](/sdk/identifying-users).

### `track(eventName, properties?)`

Record a custom event into the session timeline:

```ts theme={null}
recorder.track('checkout_started', { cartValue: 129.5 });
```

Custom events are stored alongside the replay events and carry the page URL and a timestamp. `track()` works as soon as recording has started, even before the network handshake completes.

### `flush()`

Force-flush the current event buffer immediately instead of waiting for the next `flushInterval`.

### `takeSnapshot()`

Force a fresh full DOM snapshot. You rarely need this: snapshots are taken automatically on init, on route changes, and periodically as checkpoints.

### `getSessionId()`

Returns the current backend session ID, or `undefined` if the session has not been created yet.

### `getStats()`

Returns a diagnostic snapshot: current session info, buffer stats, whether recording is active, error count, and circuit breaker state. Useful when debugging with `debug: true`.

### `destroy()`

Stops recording, flushes remaining events, and tears the recorder down. A destroyed recorder cannot be restarted; create a new instance instead.