Record and replay browser sessions — DOM snapshots, user interactions, network activity, and console logs.
Session Replay
Record browser sessions for debugging. Captures DOM snapshots, incremental mutations, mouse movements, clicks, scrolls, inputs, network requests, and console logs. Supports privacy masking, sampling, and segment-based uploads.
npm install @codmir/sdkQuick Start
Recording
import { ReplayRecorder } from '@codmir/sdk/replay';
const recorder = new ReplayRecorder({
sessionSampleRate: 0.1, // Record 10% of sessions
errorSampleRate: 1.0, // Record 100% of sessions with errors
});
const sessionId = recorder.start({ userId: 'u_123' });
// Recording is now active — DOM, clicks, scrolls,
// network, and console are all captured automatically.
// When done (e.g., on page unload)
const session = recorder.stop();Playback
import { ReplayPlayer } from '@codmir/sdk/replay';
const player = new ReplayPlayer({
container: document.getElementById('replay-container'),
speed: 1,
showCursor: true,
showClickRipple: true,
highlightErrors: true,
});
player.load(session);
player.play();Recording Configuration
import { ReplayRecorder } from '@codmir/sdk/replay';
const recorder = new ReplayRecorder({
// Sampling
sessionSampleRate: 0.1, // 10% of sessions
errorSampleRate: 1.0, // 100% of error sessions
// Limits
maxSessionDuration: 60 * 60 * 1000, // 1 hour max
segmentDuration: 5 * 60 * 1000, // 5-minute segments
// Privacy
privacy: {
maskAllInputs: false,
maskInputTypes: ['password', 'credit-card'],
maskSelectors: ['[data-private]', '.private'],
blockSelectors: ['[data-block-replay]'],
ignoreSelectors: [],
},
// Pre-send filter
beforeSend: (session) => {
// Return null to drop the session
if (session.duration < 1000) return null;
return session;
},
});Privacy Controls
| Option | Type | Default | Description |
|---|---|---|---|
maskAllInputs | boolean | false | Mask all input field values |
maskInputTypes | string[] | ['password', 'credit-card'] | Input types to always mask |
maskSelectors | string[] | ['[data-private]', '.private'] | CSS selectors to mask |
blockSelectors | string[] | ['[data-block-replay]'] | Elements to block entirely |
ignoreSelectors | string[] | [] | Elements to skip recording |
Recorder API
Start and Stop
// Start recording (returns session ID or null if not sampled)
const sessionId = recorder.start({
userId: 'u_123',
tags: { page: 'checkout', experiment: 'v2' },
});
// Check status
recorder.isActive(); // true
recorder.getSessionId(); // 'abc123...'
// Stop and get the complete session
const session = recorder.stop();Mark Errors
Link error events to the session for error-scoped replay.
import { captureException } from '@codmir/sdk/browser';
try {
riskyOperation();
} catch (error) {
const eventId = captureException(error);
recorder.markError(eventId);
}Custom Events
Add custom events to the session timeline.
recorder.addCustomEvent('checkout_started', {
cartSize: 3,
total: 99.99,
});Segment Streaming
Upload segments incrementally instead of waiting for the full session.
recorder.onSegment((segment) => {
// Upload each 5-minute segment as it completes
uploadSegment(segment);
});
recorder.onSession((session) => {
// Called when the session ends
uploadSessionMetadata(session);
});Player API
import { ReplayPlayer } from '@codmir/sdk/replay';
const player = new ReplayPlayer({
container: document.getElementById('replay'),
speed: 1,
skipInactiveThreshold: 5000, // Skip gaps > 5s
showCursor: true,
showClickRipple: true,
highlightErrors: true,
});
player.load(session);
player.play();
player.pause();
player.seek(30000); // Jump to 30s
player.setSpeed(4); // 4x speed
player.stop();
// Status
player.getState(); // 'idle' | 'playing' | 'paused' | 'ended'
player.getCurrentTime(); // ms
player.getDuration(); // ms
// Cleanup
player.destroy();Playback Speeds
0.5 | 1 | 2 | 4 | 8
Event Types
Sessions capture these event types automatically:
| Event | Description |
|---|---|
dom_snapshot | Full HTML snapshot at recording start |
dom_incremental | DOM mutations (add, remove, attribute, text) |
mouse_move | Mouse position (throttled to 50ms) |
mouse_click | Click events with position and button |
scroll | Scroll position (throttled to 100ms) |
input | Input changes (values masked per privacy config) |
viewport | Window resize events |
console | Console log/warn/error with stack traces |
network | Fetch/XHR requests with status and timing |
custom | Your custom events via addCustomEvent() |
Factory Functions
import { createReplayRecorder, createReplayPlayer } from '@codmir/sdk/replay';
const recorder = createReplayRecorder({ sessionSampleRate: 0.1 });
const player = createReplayPlayer({ container: el });TypeScript Support
import type {
ReplaySession,
ReplaySegment,
ReplayEvent,
ReplayConfig,
ReplayPrivacyConfig,
PlayerConfig,
PlaybackState,
PlaybackSpeed,
DOMSnapshotEvent,
MouseEvent,
NetworkEvent,
ConsoleEvent,
CustomEvent,
} from '@codmir/sdk/replay';