Recording controls

Conditional recording

Most sessions are healthy and not worth storing. In conditional mode the SDK keeps the last 30 seconds in memory and uploads only when a trigger fires or the baseline sample selects the session. You pay only for stored sessions.

Setting	Meaning
mode	always, conditional, triggers-only, off
baselineSampleRate	Probability a session is stored regardless of triggers
triggers	error, rage_click, dead_click, network_failure, long_task, custom:<name>, webrtc:<kind>
routes	Per-path rules: record, skip, triggers-only

These are project settings in the dashboard and are pushed to the SDK at init.

Visits and segments

A visit is one continuous run of your app in a tab and can last days. Storage happens in segments of 4 hours (configurable 1–24). Segments start at a full snapshot, so the Player stitches them into one seamless timeline.

Monitor mode

For kiosks, wall displays, and telehealth workstations. After a configurable idle period the SDK stops sampling pointer movement, drops canvas to periodic keyframes, and keeps a 60-second full-fidelity pre-roll in memory. Any error, disconnect, or custom trigger uploads the pre-roll plus a 60-second burst. Idle monitor-mode segments are free.

Backstory.setMode("monitor");                       // explicit
Backstory.track("patient_alarm", { bed: 12 }, { severity: "error" }); // custom trigger -> burst

Name the trigger custom:patient_alarm in sampling or monitor triggers. Severity is for the Custom events panel and alerts, not for whether the burst fires. See Custom events.

Governor and bandwidth

The Recorder Worker adapts to memory and network pressure through five levels (HEALTHY → PAUSED). It thins pointer data first, then canvas, then console and network detail; DOM mutations are never dropped individually. When it must shed DOM data it records an explicit gap and starts a new snapshot. The Player shows gaps with their reason.

WebRTC triggers

Every call detector is available as a trigger named webrtc:<kind>, usable in both triggers and monitorTriggers. The kinds are connect_failure, one_way_media, media_permission_denied, device_unavailable, freeze, audio_dropout, reconnect_storm, call_abandoned, packet_loss, high_latency, cpu_limited, low_resolution, and relay_fallback.

recording: {
  mode: "conditional",
  triggers: ["webrtc:connect_failure", "webrtc:one_way_media", "webrtc:freeze"],
  monitorModeAfterMinutes: 15,
  monitorTriggers: ["webrtc:freeze", "webrtc:reconnect_storm"],
}

On a telehealth workstation this is the difference between storing a twelve-hour shift and storing the four minutes a patient feed was degraded, with the minute before each incident intact. Thresholds and per-detector behavior are in WebRTC call quality.