Configuration

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

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 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.

`track(eventName, properties?)`

Record a custom event into the session timeline:

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.

Getting Started

SDK Reference

Core Concepts

Integrations

Core options

Privacy options

Delivery and session options

Callbacks

Runtime API

`identify(userId, traits?)`

`track(eventName, properties?)`

`flush()`

`takeSnapshot()`

`getSessionId()`

`getStats()`

`destroy()`

​Core options

​Privacy options

​Delivery and session options

​Callbacks

​Runtime API

​identify(userId, traits?)

​track(eventName, properties?)

​flush()

​takeSnapshot()

​getSessionId()

​getStats()

​destroy()

Core options

Privacy options

Delivery and session options

Callbacks

Runtime API

`identify(userId, traits?)`

`track(eventName, properties?)`

`flush()`

`takeSnapshot()`

`getSessionId()`

`getStats()`

`destroy()`