Session replay setup

Replay maintains a rolling in-memory view of browser activity and uploads slices around anomalies. It does not continuously upload a complete recording of every session.

Install and enable

$ npm install @askdepth/core @askdepth/replay

import { init } from '@askdepth/core';

init({
  writeKey: 'YOUR_BROWSER_WRITE_KEY',
  endpoint: 'https://YOUR_COLLECTOR/v1/telemetry',
  consent: 'unknown',
  replay: true,
});

Core dynamically imports @askdepth/replay; install it in your application even though it is loaded lazily. The recorder starts only when core collection is active, including consent and sampling checks.

By default, core derives the upload URL as /v1/replays/upload at the telemetry endpoint's origin. A custom path prefix on the telemetry endpoint is not retained. Override the full replay URL when your collector is mounted elsewhere:

import { init } from '@askdepth/core';

init({
  writeKey: 'YOUR_BROWSER_WRITE_KEY',
  endpoint: 'https://YOUR_COLLECTOR/v1/telemetry',
  consent: 'unknown',
  replay: {
    endpoint: 'https://YOUR_COLLECTOR/v1/replays/upload',
    checkoutEveryNms: 45_000,
  },
});

The React provider accepts the same replay option. Configure masking and blocking before enabling replay on pages with sensitive content.

When recording starts

Core schedules loading after the page loads, using requestIdleCallback with a three-second timeout where available, or a three-second timer otherwise. Two friction clicks within 800 ms can trigger early loading. An anomaly can also initiate loading.

Activity before the recorder starts cannot be reconstructed. A queued anomaly that predates the first snapshot may produce no usable slice.

Buffer and snapshot behavior

The default time window and full-snapshot interval are both 45 seconds. Desktop browsers use a 3 MiB buffer budget; mobile and WebKit user agents use 1.5 MiB. Pointer samples are reduced under memory pressure, and mobile/WebKit recording disables mousemove sampling.

The ring buffer protects a baseline full snapshot and the structural DOM mutations needed to reconstruct it. Those dependencies can predate the nominal 45-second activity window. A large baseline or retained structure can exceed a simple rolling-budget interpretation; the limits are pressure controls, not a hard cap on total browser memory.

Route changes request a new full snapshot, throttled to at most one per second. Canvas recording, inline images, and font collection are disabled in the default recorder configuration.

Upload behavior

Core flashes replay on rage, dead, and error-click signals, including handled errors reported through the React boundary. Replay compresses a slice, splits it into binary chunks of at most 45 KiB, and uploads sequentially with write-key authentication.

The engine refuses compressed slices above 4 MiB or 128 chunks. Replay upload retries network failures and server errors up to two additional attempts per chunk. A client rejection, including 429, stops that slice; replay's retry behavior differs from telemetry batching.