Configuration

webDeveloper

Every option accepted by ScaleBun.init(), with defaults read from the SDK's own config resolver.

Updated August 12, 2026Reviewed August 7, 2026

init() takes one object. Only clientKey and apiBaseUrl are required.

Top-level options#

Defaults are read from resolveConfig() — the function that applies them — not from a doc comment.

Option	Type	Default	What it does
`clientKey`	`string`	Required	SaaS SDK key — sent as `x-scalebun-client-key`.
`apiBaseUrl`	`string`	Required	Backend base URL, e.g. https://api.scalebun.com/api/v1
`environment`	`string`	—	—
`release`	`string`	—	—
`appVersion`	`string`	—	—
`csp`	`object`	—	Content-Security-Policy options. `nonce` is applied to every / the SDK injects, so strict-CSP sites (style-src/script-src without 'unsafe-inline') work. Optional — absent = today's behavior. On a -tag install the SDK also auto-detects the nonce from its own tag. See `csp`.
`flushIntervalMs`	`number`	`5000`	—
`sessionTimeoutMs`	`number`	—	Inactivity after which the next page load starts a NEW session (default 30 min).
`sessionMaxDurationMs`	`number`	—	Absolute cap on one session (default 24 h), so a permanently-open tab cannot report an endless session.
`maxBatchSize`	`number`	`50`	—
`maxQueueSize`	`number`	`1000`	—
`replay`	`object`	—	Session-replay sampling. Deterministic per-session decision (the SDK buckets the sessionId with the same fnv1a as flags/experiments, so the backend can re-derive it — no client trust). - 'sampled' (DEFAULT): record the FULL session from the first frame for `sampleRate` of sessions (default 1 = every session, like the mobile SDK). Dial `sampleRate` down to control volume. - 'onError': record into a rolling pre-roll buffer, flush it only when an error/rage/report signal fires (cost-saver — ships only sessions that hit a problem). `onErrorSampleRate` gates it. - 'always': record every session from start, ignoring `sampleRate`. 'off': never record. A session that isn't sampled installs NOTHING (zero overhead). See `replay`.
`replayCanvas`	`boolean`	`false`	Opt-in: capture pixels in replay (off by default — pixels can't be masked).
`signSessionLane`	`boolean`	`false`	Opt-in: HMAC-sign session/replay batches too (the analytics lane always signs). Off by default — signing multi-MB replay uploads re-enables server-side rawBody double-buffering.
`replayFrameOrigins`	`string[]`	`[]`	Cross-origin replay stitching (F-IFR P2): origins the parent bridges + a child trusts. Both the parent page and the cross-origin child must run the SDK with each other's origin listed. e.g. parent lists ['https://embed.example.com'], child lists ['https://app.example.com'].
`autocapture`	`boolean`	`true`	Autocapture DOM interactions as analytics events (on by default; text masked). Set false to opt out.
`tracePropagation`	`boolean`	`true`	Inject a W3C `traceparent` into outbound requests for FE→BE trace correlation. Default true (same-origin only — safe). Set false to disable entirely.
`tracePropagationOrigins`	`string[]`	`[]`	Cross-origin origins to ALSO propagate the traceparent to (the server must CORS-allow the `traceparent` header). e.g. ['https://api.example.com'].
`errors`	`object`	—	Error capture tuning (F-ERR). All optional — defaults need no config. See `errors`.
`network`	`object`	—	Network capture tuning (F-NET). All optional — defaults need no config. See `network`.
`performance`	`object`	—	Performance / RUM tuning (transactions, spans). All optional — defaults need no config. See `performance`.
`watchdog`	`object`	—	W5.2 — Resource Watchdog tuning (continuous resource sampling → local incidents). All optional. See `watchdog`.
`exitIntent`	`object`	—	#25 P2 — exit-intent scroll-reversal thresholds. All optional; omitted keys use REVERSAL_DEFAULTS. See `exitIntent`.
`analytics`	`object`	—	Product-analytics tuning. All optional — analytics works with none of this set. See `analytics`.
`flags`	`object`	—	Feature-flag / config options. See `flags`.
`features`	`ScaleBunFeatures`	—	—
`privacy`	`PrivacyConfig`	—	—
`bugReportOptions`	`BugReportOptions`	—	Bug-report widget (F-BUG) options. The feature is enabled via features.bugReport; these tune the optional embeddable launcher. Default: launcher off (programmatic reportBug() only).
`engageOptions`	`EngageOptions`	—	Engage options.
`push`	`object`	—	Web Push options. See `push`.
`requireConsent`	`boolean`	—	Consent-mode (GDPR/CIPA). When true, the SDK captures + sends NOTHING until the host calls `ScaleBun.setConsent(true)` (typically from a CMP callback). Default false = capture immediately.
`initialConsent`	`'granted' \| 'denied' \| 'unknown'`	—	Pre-known consent (SSR/cookie) so a host can skip the wait. Default 'unknown' when gated.
`debug`	`boolean`	`false`	—

Privacy#

Option	Type	Default	What it does
`captureNetworkBodies`	`boolean`	`false`	Capture network request/response bodies (redacted). Default false (denylist-by-default).
`denylist`	`string[]`	—	Header/body keys always stripped before send.
`maskSelectors`	`string[]`	`[]`	CSS selectors whose text/inputs are masked (in addition to mask-all defaults).
`maskReplayText`	`boolean`	`false`	Mask ALL static text in session replay (default false — text is captured so replays are readable). Set true to mask every text node. Form input VALUES have their OWN flag (`maskInputs`).
`maskInputs`	`boolean`	`false`	Mask form input VALUES in session replay. By default this follows `maskReplayText` — one flag governs everything (static text + typed inputs). Set it explicitly (`true`/`false`) to decouple inputs from text. Password fields are ALWAYS blanked regardless of this flag.
`respectDnt`	`boolean`	`false`	Honor the user's Global Privacy Control / Do-Not-Track signal (default false). When true and the browser signals opt-out (`navigator.globalPrivacyControl` / `navigator.doNotTrack`), session replay does not record for that user. Recommended where GPC compliance (e.g. CCPA) matters.
`maskEventText`	`boolean`	`false`	Mask the TEXT LABEL on captured interaction events (default false — the real label is sent).

Resolved option	Default
`consent.required`	`false`
`consent.initial`	`'unknown'`
`bugReport.launcher`	`false`
`bugReport.position`	`'bottom-right'`
`bugReport.label`	`'Report a bug'`

Nested blocks#

These are passed through the resolver untouched and defaulted inside the feature that reads them, so the defaults below come from the contract rather than from resolveConfig.

`replay`#

Option	Type	Default	What it does
`mode`	`ReplayMode`	—	—
`sampleRate`	`number`	—	—
`onErrorSampleRate`	`number`	—	—
`persistBuffer`	`boolean`	`false`	Opt-in: mirror the pre-roll buffer to IndexedDB so a tab-killing crash still yields it on the next load (an error-free clean close discards it).
`privacyLevel`	`'standard' \| 'strict'`	`'standard'`	'strict' adds heuristic PII redaction (emails / card numbers / SSNs) to captured text — useful when replay text is UNMASKED (privacy.maskReplayText).

`errors`#

Option	Type	Default	What it does
`ignoreErrors`	`(string \| RegExp)[]`	—	Drop errors whose MESSAGE matches (substring or RegExp). Merged with built-in benign noise (e.g. "ResizeObserver loop…") — your list is appended, never replaces the defaults.
`denyUrls`	`(string \| RegExp)[]`	—	Drop errors whose originating script URL matches (substring or RegExp) — silence noisy third-party scripts (chrome-extension://, ad/analytics vendors, …).
`captureResourceErrors`	`boolean`	—	Capture failed resource loads (img/script/link/css) as 'resource' errors instead of dropping them. Default false — they're usually noise, and never JS crashes.
`maxBreadcrumbs`	`number`	`50`	Max breadcrumbs retained in the ring + attached to each error (the trail of console/network/ navigation/click events leading up to it). Default 50, max 200.
`sampleRate`	`number`	`1`	Cost lever for very-high-volume apps: fraction of SESSIONS (0–1) whose AUTO errors are captured (deterministic per-session; manual captureError always fires). Default 1 = every session. Prefer grouping / ignoreErrors / beforeSend first — sampling trades error completeness for cost.
`beforeSend`	`(item: ErrorItem) => ErrorItem \| null`	—	Last-mile hook: inspect/transform each error item before it's sent, or return null to DROP it (e.g. scrub fields, drop by URL/tag). Throwing is safe — the original is kept.
`beforeBreadcrumb`	`(crumb: Breadcrumb) => Breadcrumb \| null`	—	Hook: inspect/transform each breadcrumb before it enters the ring, or return null to drop it.

`network`#

Option	Type	Default	What it does
`trackWebSocket`	`boolean`	`true`	Track WebSocket connection lifecycle + message/byte counters. Default true (lazy chunk).
`trackSse`	`boolean`	`true`	Track Server-Sent-Events (EventSource) lifecycle. Default true (lazy chunk).
`captureBodies`	`boolean`	`false`	Opt-in: capture request/response bodies + headers (redacted + capped). Default false (privacy).
`bodyMaxBytes`	`number`	`8192`	Hard cap on captured body bytes when captureBodies is on. Default 8192, ceiling-enforced.
`contentTypeAllowlist`	`string[]`	`['application/json','text/plain']`	Content-types eligible for body capture.
`sampleRate`	`number`	`1`	Base sample rate (0–1) for SUCCESSFUL requests — failed/slow are ALWAYS kept.
`slowRequestMs`	`number`	`2000`	"slow" threshold in ms — requests at/over this are flagged + always kept.
`denyUrls`	`(string \| RegExp)[]`	—	Never capture requests whose URL matches (substring or RegExp).
`beforeSend`	`(item: NetworkItem) => NetworkItem \| null`	—	Last-mile hook: transform the network item, or return null to DROP it. Throwing is safe.

`performance`#

Option	Type	Default	What it does
`tracesSampleRate`	`number`	`1`	Base sample rate (0–1) for transactions. SLOW/errored transactions are ALWAYS kept regardless; this only thins the fast, clean ones. Deterministic per-transaction (re-derivable from traceId). Default 1 = keep every transaction.
`slowTransactionMs`	`number`	`3000`	Duration (ms) at/over which a transaction is "slow" → always kept (the adaptive bias).

`watchdog`#

Option	Type	Default	What it does
`sampleRate`	`number`	`1`	Per-session deterministic keep rate (0–1).
`heartbeatMs`	`number`	`1000`	Event-loop-lag heartbeat cadence (ms). Default 1000, floored at 250.
`rollupMs`	`number`	`30000`	Health-rollup window (ms) — one resource_health item per window.
`memorySampleMs`	`number`	`20000`	Heap sample cadence (ms).
`thresholds`	`Record<string, number>`	—	Incident-threshold overrides (see the WatchdogThresholds keys).
`captureProfileOnIncident`	`boolean`	`true`	5.3 — capture a JS Self-Profiling window on an incident (no-op until the header + phase land).

`exitIntent`#

Option	Type	Default	What it does
`windowMs`	`number`	`120`	How far back to measure upward velocity (ms).
`minDistancePx`	`number`	`80`	Minimum upward travel across the window (px) — filters micro-corrections.
`minVelocityPxMs`	`number`	`0.7`	Minimum upward velocity (px/ms). Default 0.7 (≈700 px/s) — a flick, not a drift.
`minDepthPct`	`number`	`25`	Engagement floor: minimum max scroll depth reached (%).
`sustainSamples`	`number`	`3`	Consecutive qualifying samples required (hysteresis vs scroll jitter).
`topEdgePx`	`number`	`40`	Pointer-exit band: how close to the top edge (px) the pointer must be when it leaves the page.

`analytics`#

Option	Type	Default	What it does
`plan`	`TrackingPlan`	—	A3 — optional typed tracking plan. Governs custom `track()` events (internal `$` events are never governed): warns on unknown events / missing-required / type-mismatch props, and — in `strict` mode — DROPS violations from both lanes.
`sampleRate`	`number`	—	A6 — analytics-lane sample rate (0–1, default 1 = keep all). Sampling is PER-USER + deterministic (a stable subset of anonymous ids is kept in full, so funnels/retention stay intact). Identity ($identify/$group/$alias) and revenue (purchase) events are NEVER thinned.
`cookieDomain`	`string`	—	A6 — set to share the anonymous id across sub-domains via a cookie (e.g. '.example.com'), so a user is one profile across app./www./shop. When unset, the id is localStorage-scoped per origin.

`flags`#

Option	Type	Default	What it does
`bootstrap`	`FlagsBootstrap`	—	F3 — bootstrap seed applied synchronously at init (SSR handoff) so the first paint uses real values instead of defaults — no flash-of-default on a cold cache. Shape mirrors GET /config.
`realtime`	`boolean`	`true`	F4 — subscribe to the realtime config stream (SSE) so a kill-switch flip / flag edit reaches the client in seconds instead of waiting for the periodic refresh. set false to rely on the foreground-poll refresh only (no persistent connection).

`push`#

Option	Type	Default	What it does
`softAsk`	`object`	—	—

`csp`#

Option	Type	Default	What it does
`nonce`	`string`	—	—

Top-level options#

Privacy#

Consent and bug report#

Nested blocks#

replay#

errors#

network#

performance#

watchdog#

exitIntent#

analytics#

flags#

push#

csp#