SDK configuration reference

Backstory.init(config) validates its input, applies defaults, and logs a single console.warn listing anything invalid. It never throws. Only projectKey is required.

Top-level options

Option	Type	Default	Notes
projectKey	string	required	Public project key (pk_live_…). pk_dev_local in local development.
ingestUrl	string	https://ingest.backstory.io/v1/ingest	Local: http://localhost:8080/v1/ingest.
apiUrl	string	ingest origin	Base URL for remote config (GET /v1/config). Local: http://localhost:8081.
spill	boolean	true	IndexedDB write-behind for un-acknowledged chunks; survives tab crashes.
release	string	—	Your release identifier, used for source maps and release health.
environment	string	—	production, staging, …
endUserId	string	—	Your id for the person, stored exactly as sent.
endUserName	string	—	Display name shown wherever the session is listed. Same as the second argument to identify().
debug	boolean	false	Mounts the debug panel (Ctrl+Shift+R toggles it).
workerUrl	string	inlined	URL of dist/worker.js when you prefer a separate worker file.

privacy

Option	Type	Default	Notes
mode	"strict" | "permissive"	"strict"	Privacy mode on or off. The project setting in the dashboard overrides it. See Privacy configuration.
maskSelector	string	""	Extra selector whose subtree is masked.
blockSelector	string	""	Extra selector whose subtree is removed (box kept).
allowUnmask	boolean	false	Honor data-backstory-unmask while privacy mode is on.

consent

Option	Type	Default	Notes
required	boolean	false	When true, nothing is captured or buffered until consent is granted.
adapter	"tcf" | "onetrust" | "cookiebot" | "osano" | "callback"	—	Auto-wires a consent platform.
purposeIds	number[]	[1, 7, 8, 10]	TCF purposes that must all be granted.
callback	(grant, revoke) => void	—	For adapter: "callback".
ignoreGPC	boolean	false	Treat Global Privacy Control as opt-out unless true.

recording

Option	Type	Default	Notes
sampling	Partial<SamplingPolicy>	{ mode: "always" }	See Recording controls.
memoryBudgetMB	number	24	Hard ceiling for in-memory buffers. Auto-lowers to 8 on low-end devices.
batchMs	number	1000	Flush interval.
batchBytes	number	65536	Flush when a batch reaches this size.
pointerHz	number	20	Pointer sampling in HEALTHY; the governor lowers it under pressure.
checkpointMinutes	number	5	Full snapshot interval.
segmentHours	number	4	Segment rollover (1–24).
inactivityMinutes	number	30	Ends a normal-mode session after inactivity.

network

Option	Type	Default	Notes
captureMeta	boolean	true	Method, path, status, duration, size, timing. Query strings and userinfo are stripped.
captureBodies	boolean	false	Bodies only for bodyAllowlistUrls, masked, capped by maxBodyBytes.
headerAllowlist	string[]	[]	Authorization, Cookie, and Set-Cookie are never captured.
bodyAllowlistUrls	string[]	[]	URL prefixes.
maxBodyBytes	number	65536
captureWebSocketMessages	boolean	false	Opt in to masked text frame capture. Connection and frame metadata is already captured by default. Ignored in strict privacy mode.
webSocketMessageAllowlistUrls	string[]	[]	Required URL prefixes for WebSocket message text. An empty list captures no payloads.
maxWebSocketMessageBytes	number	4096	Maximum captured UTF-8 bytes per text frame (128–65536).

WebSocket metadata includes the sanitized connection URL, lifecycle, close code, duration, sent/received frame counts, direction, text/binary type, and byte size. To inspect message text in Network → WebSocket, explicitly allowlist only the endpoints you need:

Backstory.init({
  projectKey: "pk_live_…",
  network: {
    captureWebSocketMessages: true,
    webSocketMessageAllowlistUrls: ["wss://realtime.example.com/support/"],
    maxWebSocketMessageBytes: 4096,
  },
});

Text is truncated and PII-masked in the browser. Binary frame contents are never captured.

collectors

Each defaults to true: console, network, vitals, longTasks, errors. Remote config can turn any of them off without a deploy.

webrtc

Off by default. See WebRTC call quality for what is captured and the privacy rules.

Option	Type	Default	Notes
enabled	boolean	false	Loads the lazy WebRTC module when true.
sampleIntervalSec	number	5	Seconds between emitted quality samples at full health; getStats() is polled at 1 Hz internally.
captureSdp	boolean	false	Redacted session descriptions. Never honored in strict privacy mode.
emitOnThresholdCross	boolean	true	Emit immediately when a detector threshold is crossed, even while thinned.
maxPeerConnections	number	8	Tracked at once; extras counted but not sampled.

Public API

Backstory.init(config);
Backstory.identify(id, traits?);
Backstory.track(name, props?, { severity?: "debug" | "info" | "warn" | "error" }); // see Custom events
Backstory.checkpoint();             // force a full snapshot
Backstory.setMode("normal" | "monitor");
Backstory.consent.grant(); Backstory.consent.revoke();
Backstory.optOut();                 // stop, wipe local state, send a final consent=false
Backstory.forceRecord(reason);      // promote a conditionally buffered session
Backstory.stop();
Backstory.getSessionId(); Backstory.getVisitId(); Backstory.getDebugState();

Backstory.webrtc.attach(pc);        // instrument a connection built before init
Backstory.webrtc.list();            // tracked connections with live quality
Backstory.webrtc.report(sample);    // hand us stats from a vendor SDK

Backstory.track() records application-defined diagnostic events with optional severity. They appear in the Custom events panel, not the mixed Events stream. Full reference: Custom events.

Remote configuration

At init the SDK fetches GET {apiUrl}/v1/config?key=…&sdk=… with a 300 ms timeout and caches the result for five minutes. Server values override local ones for: recording on/off, sampling, privacy mode, canvas, memory budget, segment and checkpoint intervals, monitor mode, collectors (including WebRTC), feature flags, and a forced governor level for incident response. Every ingest acknowledgement can carry small config nudges as well.