Replay API reference

Use the low-level replay engine and understand flash results, cooldowns, and test seams.

@askdepth/replayv0.3.0

On this page

Core integration handles consent, sampling, anomaly subscriptions, and lazy loading. Use the low-level engine only when your application needs to own those responsibilities.

Create an engine

import { createReplayEngine } from '@askdepth/replay';

const replay = createReplayEngine({
  sessionId: crypto.randomUUID(),
  writeKey: 'YOUR_BROWSER_WRITE_KEY',
  environment: 'production',
  endpoint: 'https://YOUR_COLLECTOR/v1/replays/upload',
});

// Start only after the relevant consent has been granted.
replay.start();

// When your application detects a relevant anomaly:
const payloads = await replay.flash(crypto.randomUUID());

// On consent withdrawal or disposal:
replay.stop();

This example shows the lifecycle in sequence. In an application, invoke each method from the corresponding consent, anomaly, or disposal event. Keep one session identifier consistent with related telemetry if you need correlation.

Direct engine use does not consult core consent, sampling, or kill state. It also does not automatically subscribe to core anomalies. Avoid running a direct engine alongside core-managed replay unless you intentionally want multiple recorders.

Configuration

Option	Default	Meaning
`sessionId: string`	Required	Session identifier attached to the slice.
`writeKey: string`	Required	Browser write key for chunk authentication.
`environment: string`	Required	Environment attached to the manifest.
`endpoint: string`	Required	Full replay upload URL.
`windowMs?: number`	`45000`	Activity window; keep it compatible with the contract's 45-second maximum duration.
`checkoutEveryNms?: number`	`45000`	Recorder full-snapshot interval.
`maxBytes?: number`	User-agent based	Ring-buffer pressure budget.
`userAgent?: string`	Browser user agent	Determines mobile/WebKit recording defaults.

Additional options now, clock, schedule, fetchImpl, recorder, compress, and memoryPressure support controlled integrations and tests. They are advanced seams; changing them can alter recording, privacy, scheduling, or delivery behavior.

Instance methods

Method	Behavior
`start(): void`	Starts recording; repeated calls while running are ignored.
`stop(): void`	Stops the recorder, clears buffer/sanitizer state, and removes route/visibility listeners.
`push(event): void`	Sanitizes and queues an rrweb-shaped event. It does not require `start` to have run.
`dump(): RRWebEvent[]`	Returns the current buffer slice; it does not flush the scheduled pending queue first.
`flash(anomalyId, triggerTimestamp?): Promise<ReplayUploadPayload[]>`	Flushes pending events, creates/compresses chunks, and attempts upload. Timestamp defaults to epoch milliseconds now.

Concurrent flash calls share the in-flight result. A call within one second of a completed nonempty flash can reuse its payloads. Consequently, not every anomaly ID necessarily receives a distinct slice.

An empty buffer or an oversized slice returns []. Upload failures are caught by the engine: it logs a generic warning, stops further chunks, and can still return the generated payload array. A resolved promise is not a receipt.

stop() clears recording state but does not promise to abort an already running upload. Integrations that need transport cancellation must own that policy.

Utility exports

The package also exports RingBuffer, maxBufferBytes, compressBytes, createRecordOptions, EventSanitizer, createEventSanitizer, sanitizeEvent, maskText, and maskInputValue, plus buffer/chunk constants and replay contract types.

createRecordOptions builds options for your own rrweb recorder. createReplayEngine applies its own default options and does not accept a maskTextSelector setting directly. For stream sanitization, prefer one createEventSanitizer() instance per stream; masking state tracks node IDs across snapshots and mutations.

Last reviewed October 12, 2026SDK issue?