Session replay (SDK)

For privacy defaults, sampling and how replay works end to end, read the session replay guide. This page is the SDK surface.

Enabling recording

Recording is remote-first: enabling session replay in the project’s panel settings is enough. /decide returns {"sessionRecording": {"enabled": bool, "sampleRate": float}}, and when enabled is true the SDK lazy-loads the replay code and starts recording (subject to sampling) — no code change or deploy needed. Turning it off in project settings stops new recordings within seconds, the same way.

The sessionRecording init option adjusts that behavior locally:

kilden.init('YOUR_WRITE_KEY', {
  sessionRecording: true, // or a SessionRecordingOptions object
});

Value	Behavior
unset (default)	Remote config decides: the replay chunk loads and records automatically when the project has recording enabled. A manual startSessionRecording() also loads it
true or options object	Loads the replay chunk eagerly (without waiting for /decide) and records subject to sampling and the project’s remote kill switch
false	Hard opt-out. Never records, the replay code is not even downloaded, and remote config cannot turn it on — a local false always wins

See SessionRecordingOptions for sampleRate, minimumDurationMs, masking and canvas options.

Methods

kilden.startSessionRecording(); // force-start (also loads the chunk if needed)
kilden.stopSessionRecording();
kilden.getReplayId(); // string while recording, null otherwise

While the replay package hasn’t loaded, all three are safe no-ops (getReplayId returns null) that log a warning with debug: true.

Sampling is sticky

Whether a session is recorded is decided once per session and persisted: reloads within the session keep the same decision, and the dice re-roll when the session rotates (30 minutes of inactivity). A recording never spans two sessions — rotation cuts it.

Correlation with analytics

Recordings share the session id with events: the replay of a session is always joinable 1:1 with its event timeline. When a recording starts, the SDK emits a $session_recording_started event so you can query or filter sessions that have a replay.