Skip to content
bucker

@bucker/browser

Browser capture. Named exports only, integrations importable from their own entry points, no side effects at import time — the package is tree-shakable by construction and a test enforces its byte budget in CI.

Distribution note. The package is build-ready, not yet published. It carries a publishConfig (pointing at dist/, split per subpath) alongside a source-pointing top-level main/types/exports — the split matters because several other workspace packages import the SDKs by source with no build step, while a published consumer cannot compile ./src and needs the compiled dist/. pnpm build / prepack run scripts/build-package.mjs, which refuses to finish if the built output does not match what publishConfig.exports promises. Inside the monorepo it resolves through workspace:*; create-bucker already emits the install command for the published name. What remains is an actual npm publish, a human decision covered in sdks/PUBLISHING.md — not code readiness.

Init

import { init } from '@bucker/browser'

init({
  dsn: import.meta.env.VITE_BUCKER_DSN,
  environment: import.meta.env.MODE,
  release: __APP_VERSION__,
})

Call it once, as early as your entry allows. init() returns the Client and also installs it as the current client, so the module-level helpers work anywhere after.

Options

Everything on ClientOptions, plus the browser-specific ones:

Option Default Meaning
dsn — Required. A DSN still holding the documentation placeholder (<publicKey>, PUBLIC_KEY, …) disables the SDK with a warning rather than sending to a project that does not exist
release — Stamped on every event, and required for release health: without it no session is sent (the server discards release-less sessions), and the SDK says so once in the console
environment, dist, serverName, platform — Stamped on every event
sampleRate 1 Applied per event before the envelope is built; drops are accounted for in the client report
maxBreadcrumbs SDK default Ring-buffer size
maxValueLength SDK default Caps any single captured string. Bounds sizes, never semantics
beforeSend — Last chance to mutate or drop an event; a drop is accounted for
beforeBreadcrumb — Same, per breadcrumb
beforeSendSpan, beforeSendLog — Same, for spans (@bucker/sdk-core/tracing) and structured-log records (/logging); return null to drop. Counted as before_send
inAppInclude / inAppExclude — Substring matchers forcing frames in or out of in_app; include wins
integrations defaultIntegrations() Replaces the default set entirely
autoUnloadFlush true Set false to skip the pagehide/visibilitychange beacon flush
maxBufferBytes SDK default Transport queue ceiling
tunnel — A same-origin path (/bucker) to send envelopes to instead of the ingest host. See Sending through your own origin
random, now Math.random, Date.now Testing seams for deterministic sampling and timestamps

Default integrations

defaultIntegrations() returns [globalHandlersIntegration(), breadcrumbsIntegration(), httpContextIntegration()].

globalHandlersIntegration — window.onerror and unhandledrejection. Both are recorded with handled: false and a distinct mechanism type, because "the app crashed" and "someone caught this and reported it" group differently and the distinction cannot be recovered later. An onerror that fires with no Error object (cross-origin scripts) still produces an event built from filename/line/column — a location-only crash beats no crash.

breadcrumbsIntegration — console, fetch, XMLHttpRequest, history navigation and DOM clicks. Every source is a monkey patch and every patch is reversible: the integration keeps the original and restores it on teardown.

DOM click crumbs carry a micro-DOM chain (microDomChain, exported from @bucker/browser/microdom) — a compact ancestor description rather than a full selector dump.

httpContextIntegration — the page the error happened on and the browser that raised it: request.url is location.href, and request.headers carries User-Agent and, when there is one, Referer. This is what fills an issue's Request panel for a browser event. Both URLs are masked the same way breadcrumb URLs are: userinfo is dropped and every query and fragment value becomes [Filtered], while the keys stay — /cart?token=abc&page=2 arrives as /cart?token=[Filtered]&page=[Filtered]. A request already on the event (from setRequest, a scope, or your own event processor) is left untouched.

Transport

Two send paths share one queue:

  • normal — fetch with keepalive;
  • unloading — navigator.sendBeacon, the only delivery a browser guarantees after the page is gone. installUnloadFlush flips a flag on pagehide / visibilitychange; the transport reads it rather than swapping implementations, because there is no time to negotiate anything at that point.

sendBeacon caps a payload at 64 KB (BEACON_MAX_BYTES), so splitForBeacon splits oversized queues rather than losing them.

Both paths send Content-Type: text/plain;charset=UTF-8, not the envelope type, and authenticate in the query string, so every send is a CORS-simple request with no preflight. For the beacon that is not an optimisation: the Beacon spec makes every beacon credentialed, the ingest host answers preflights with Access-Control-Allow-Origin: * and no credentials (deliberately — there is nothing to protect with cookies there), and a credentialed request can never pass that preflight. The browser would drop the POST while sendBeacon still returned true. Ingest reads the body as raw bytes whatever the type says.

Envelopes ride two priority lanes. Errors take the critical lane and flush first; logs, spans, replay and attachments take bulk. A bulk item never shares an envelope with an error item — one oversized attachment causing a 413 that also kills the error event is a footgun we deliberately do not inherit.

Rate limits (429 + Retry-After / X-Sentry-Rate-Limits) are honoured per category, and everything dropped is reported back as a client_report with a reason (ratelimit_backoff, queue_overflow, sample_rate, before_send, …).

Filtering noise before it costs quota

ignoreErrors, denyUrls, allowUrls and thirdPartyFrames drop an event in the SDK, before sampling and before it is sent. In the browser they live in their own entry point (the root bundle is at its size budget), so you add the integration:

import { defaultIntegrations, init } from '@bucker/browser'
import { inboundFiltersIntegration } from '@bucker/browser/filters'

init({
  dsn,
  integrations: [
    ...defaultIntegrations(),
    inboundFiltersIntegration({
      ignoreErrors: ['ResizeObserver loop', /^Script error\.?$/],
      denyUrls: [/^chrome-extension:\/\//, /extensions\//],
      thirdPartyFrames: 'drop', // or 'tag'
    }),
  ],
})
Option Meaning
ignoreErrors Drop when the message, an exception value, or Type: value matches. A string is a substring, a RegExp is tested
denyUrls Drop when the top-most frame's file matches
allowUrls Drop when the top-most frame's file matches none of these. An event with no frames is kept
thirdPartyFrames A frame with no registered Debug ID is third-party. 'drop' discards an event whose frames are all third-party; 'tag' keeps it with tags.third_party_code. Does nothing until the bundler plugin has registered a chunk, since nothing can be told apart before that

Every drop is a client_report with reason event_processor, so the dashboard still shows how much noise the list sheds. Server SDKs (@bucker/node) take the same four options on init() directly.

Sending through your own origin (tunnel)

Ad blockers match ingest hostnames. A blocked ingest is invisible by construction: nothing arrives, so nothing is counted, and the outcome vocabulary cannot show it. tunnel sends the browser's envelopes to a path on your origin and lets your server forward them:

init({ dsn: process.env.NEXT_PUBLIC_BUCKER_DSN, tunnel: '/bucker' })
// app/bucker/route.ts (Next.js App Router)
import { tunnelRoute } from '@bucker/node/nextjs'

export const POST = tunnelRoute({ dsns: [process.env.NEXT_PUBLIC_BUCKER_DSN] })

The envelope still carries the DSN in its header, so the SDK adds no auth query string. The route reads only the project id from that header and forwards to the DSN you listed with its host and key: a request naming any other project gets a 403, and the route cannot be aimed at another host. Bodies are capped at the protocol's envelope ceiling, redirects are refused, and the upstream body is never relayed (only the status and Retry-After / X-Sentry-Rate-Limits, so the SDK's backoff still works). @bucker/node/tunnel exports the same handler for any Request -> Response runtime (Hono, Workers, Deno, Bun).

What it costs, honestly:

  • Every browser event becomes a request to your host (a serverless invocation on Vercel), and you pay for it. Pair it with sampleRate, ignoreErrors and the unload-time beacon limits.
  • The ingest sees your server's address as the client, not the visitor's.
  • A path called /bucker is as blockable as a hostname if everyone uses it. Pick your own.

Script-tag delivery (no bundler)

For WordPress, static HTML and CMS templates that cannot npm install. There is deliberately no server-configured loader: a lazy "error-only" stub loses the breadcrumbs and early fetches that happen before the real SDK arrives. The files below are the whole SDK, loaded eagerly from a CDN you pin to a version.

The classic script (recommended; it is the one that takes SRI):

<script
  src="https://cdn.jsdelivr.net/npm/@bucker/browser@0.1.0/dist/0.1.0/bucker.min.js"
  integrity="sha384-…"
  crossorigin="anonymous"
  data-dsn="https://<publicKey>@us.ingest.bucker.io/<projectId>"
  data-release="site@2026.10.17"
  data-environment="production"
></script>

data-dsn initialises the SDK as the tag runs (also data-release, data-environment, data-tunnel). Without it nothing runs, and you call Bucker.init({ dsn }) yourself; the whole SDK is the global Bucker, including Bucker.inboundFiltersIntegration for deny lists.

Get the integrity value for the version you pin from the build (pnpm --filter @bucker/browser build prints it and writes dist/<version>/bucker.min.js.integrity), or compute it from the file you are about to reference:

curl -s https://cdn.jsdelivr.net/npm/@bucker/browser@0.1.0/dist/0.1.0/bucker.min.js \
  | openssl dgst -sha384 -binary | openssl base64 -A

Pin an exact version, never @latest or a range: SRI on a moving file breaks the day it moves, and an unpinned third-party script on every page is a supply-chain hole you chose.

There is no unversioned path to pin by accident. The build publishes the script only as dist/<version>/bucker.min.js, beside bucker.min.js.integrity (its SHA-384 value) and the source map, with the version copied from the package's package.json; an unversioned bucker.min.js directly under dist does not exist. The SDK itself never fetches code at run time: no import() of a URL and no <script> element created from code appears in any entry point or in the script-tag build (test/no-mutable-path.test.ts), so every feature is code you imported and your SRI hash covers.

The ES module (no SRI):

<script type="module">
  import { init } from 'https://cdn.jsdelivr.net/npm/@bucker/browser@0.1.0/+esm'
  init({ dsn: 'https://<publicKey>@us.ingest.bucker.io/<projectId>' })
</script>

An inline module script cannot carry integrity, and jsDelivr's +esm is generated on request and bundles the protocol's schema library, so it is several times larger than the classic script. Use it when you already author modules; use the classic script otherwise.

The classic script is about 42 KB minified (about 15.7 KB gzipped) and has its own budget in test/iife.test.ts; every opt-in entry point has a gzip budget as well as a minified one (test/size.test.ts). It stubs the schema library the server uses for validation (the SDK only serialises), which is why it is a fraction of the size of the ES module.

User feedback

import { captureException } from '@bucker/browser'
import { captureFeedback } from '@bucker/browser/feedback'

const eventId = captureException(error)
captureFeedback({ message, email, associatedEventId: eventId })

@bucker/browser/feedback is its own entry point (the root bundle is at its budget). It sends a Sentry-shaped feedback item that the server stores and links to the issue. The embeddable widget and the post-error report dialog are @bucker/browser/feedback-widget, a separately budgeted entry; see User feedback. The widget's optional screenshot (allowScreenshot, a file the user picks, never an automatic capture) is stored only on a project that opted in to screenshots. @bucker/browser/attachments exposes addAttachment; the files ride their own bulk envelope and show on the event's Attachments panel. See @bucker/node.

Feature flags

Records which flags an error saw, so an issue can answer "which flag broke this". The server reads contexts.flags from every event and rolls it up per issue; this is the producer. Flag SDKs (LaunchDarkly, Statsig, Unleash, Flagsmith…) come through their OpenFeature providers, so one hook covers them and this package depends on none of them:

import { OpenFeature } from '@openfeature/server-sdk' // or @openfeature/web-sdk
import { openFeatureHook } from '@bucker/browser/flags'

OpenFeature.addHooks(openFeatureHook())

Evaluations are recorded on the current scope, so on a server a request's flags land on that request's errors only. A flag evaluated again keeps its latest record; at most 50 are kept (the server's own ceiling), stalest first out.

Hook contract v2. The hook's finally stage (OpenFeature 0.9 passes it the full evaluation details, for a failed evaluation too) records { flag, variant, reason, version, provider, valueDigest, evaluatedAt, requestId?, definitionsLoadedAt? }, so "variant B of checkout at version 7 raised this error" is a join on stored keys. The value is customer data: it is kept (as result) only for booleans and strings of 40 characters or fewer, and anything else, an object, a number or a longer string, is reduced to its SHA-256 valueDigest. A failed evaluation is recorded with reason ERROR and its error code, and suspect ranking ignores it: the caller got the default, not a decision the flag system made. version is read from the provider's flagMetadata.version. With an OpenTelemetry span active, the hook also adds the semantic-convention feature_flag.evaluation event to it (feature_flag.key, feature_flag.result.variant, feature_flag.result.reason, feature_flag.provider.name, feature_flag.version), which is how a trace shows which variants a request saw: the server folds the events into one bucker.flags attribute on the trace's local root span, and spans from a non-Bucker OpenTelemetry SDK that carry feature_flag.* attributes or events are read the same way. Without OpenFeature, call recordFlagEvaluation(flag, result) yourself (the v1 shape, no variant). The Python and Dart hooks are not part of this release.

setTrackingConsent('granted' | 'pending' | 'revoked') gates everything the SDK sends (errors, sessions, spans, logs, replay, client reports), because it sits on the transport, not on capture:

import { init } from '@bucker/browser'
import { setTrackingConsent, trackingConsentIntegration } from '@bucker/browser/consent'

init({ dsn, integrations: [...defaultIntegrations(), trackingConsentIntegration({ initial: 'pending' })] })
// later, from your consent banner:
setTrackingConsent('granted') // or 'revoked'
  • pending: nothing leaves the page. Requests wait in a bounded buffer (50 by default); past it the oldest is evicted and counted as queue_overflow.
  • granted: the buffer is sent, in order, and sends flow.
  • revoked: the buffer is discarded, nothing is sent, and the release-health session is ended (a later grant starts a new one). This is deliberately not reported in the client report: a report is itself telemetry, and withdrawn consent asks for silence.

To gate the very first events, install the integration at init as above. Calling setTrackingConsent without it installs the gate from that moment on. Requests already handed to the network when consent is revoked cannot be recalled.

Offline queue

A tab that goes offline loses its in-memory buffer when it closes, including the errors that explain why it was offline. @bucker/browser/offline keeps unsent envelopes in IndexedDB and replays them, oldest first, when the network returns or the app next starts:

import { offlineQueue } from '@bucker/browser/offline'

const offline = offlineQueue({ maxEntries: 30, maxAgeMs: 24 * 60 * 60 * 1000 })
init({
  dsn,
  fetchImpl: offline.fetch,
  integrations: [...defaultIntegrations(), offline.integration],
})

It wraps fetch rather than the core transport so a failure becomes "queued durably" before it is counted as a network_error drop (otherwise one envelope would be reported lost and delivered). Anything the queue gives up on, because of the size cap or maxAgeMs, is counted as cache_overflow in the client report, per category. A 429 or 5xx on replay keeps the entry; any other 4xx removes it (the server will never accept that payload).

Limits, stated: the unload-time sendBeacon path does not go through fetch, so an envelope beaconed while offline as the page closes is not queued; and where IndexedDB is unavailable (some private windows) it falls back to memory, with one console warning, which is not durable.

Automatic spans (@bucker/browser/tracing)

import { defaultIntegrations, init } from '@bucker/browser'
import { browserTracingIntegration } from '@bucker/browser/tracing'

init({
  dsn,
  tracesSampleRate: 0.1,
  integrations: [...defaultIntegrations(), browserTracingIntegration()],
})

Opt-in, in its own entry point with its own size budget (about 10 KiB minified on its own, because it carries the tracer the default bundle does not), so a page that does not trace pays nothing. With no tracesSampleRate or tracesSampler it patches nothing.

Span When Notes
pageload <path> navigation start to the load event, plus an idle window Navigation Timing as attributes (http.ttfb_ms, dom.content_loaded_ms, load_ms)
navigation <path> pushState, replaceState, popstate to a new URL A new trace; ends the previous page span
fetch <METHOD> <path>, xhr <METHOD> <path> each request Child of the current page span; carries the status code

Names and attributes carry the path only: query strings and fragments are dropped. A traceparent header is added to same-origin requests only; list cross-origin hosts in tracePropagationTargets (strings match as substrings, RegExps are tested), because a header on a cross-origin request triggers a CORS preflight and tells a third party your trace ids. Options: pageload, navigation, fetch, xhr (each default on), idleTimeoutMs (default 1000). teardown() restores every patched global.

Capturing by hand

import { captureException, captureMessage, addBreadcrumb, setUser, setTag,
         setContext, setExtra, flush, close } from '@bucker/browser'

captureException(error, { mechanism: { type: 'checkout', handled: true } })
captureMessage('cart reconciliation skipped', 'warning')
addBreadcrumb({ category: 'checkout', message: 'coupon applied', level: 'info' })
setUser({ id: 'u_123' })          // pass null to clear
setTag('tier', 'pro')
await flush(2000)                 // true when the queues drained in time

Scope is exported for advanced use; getCurrentScope() returns the active one.

Session replay

Bucker replay records what the user did, not what the screen showed: navigations, clicks, inputs (masked by default), requests, console errors, scrolls and vitals. It never captures the screen, the DOM or text nodes, and that is by design — there is no video for a misconfiguration to leak, so the privacy answer to your DPO is "Bucker cannot capture your users' screens". What you get instead is the replay list (find sessions by user, URL, browser, release, errors, rage and dead clicks), a scrubbable player linked to traces, logs and backend errors, a shareable link at a timestamp with the network waterfall, and a transcript your coding agent can run as a repro script. The full capture inventory is in Session replay privacy.

Its own entry point, @bucker/browser/replay, so an application that never calls replayIntegration() does not pay for it — the root bundle stays under the CI-enforced byte budget:

import { init, defaultIntegrations } from '@bucker/browser'
import { replayIntegration } from '@bucker/browser/replay'

init({
  dsn,
  integrations: [...defaultIntegrations(), replayIntegration()],
})

By default it is error-triggered, not always-on: a ring buffer holds the last 30 seconds / 200 events of interaction (windowMs, maxEvents) and nothing leaves the page until an error is captured, at which point the slice is sent on its own bulk-lane envelope so a 413 on the replay bytes can never take the error event down with it. Segments are rate-limited to one per minSegmentIntervalMs (default 5000) however many errors fire in that window, and sampleRate (default 1) thins which errors get a segment at all.

Option Default Meaning
maskAllText true Mask all page text and input values. false still never captures credential-shaped fields
maxTextLength 48 Cap on captured input values and click labels before they are clipped. At most 255: a larger value is clamped, because the server bounds these fields at 256 characters and rejects the whole segment over it (a clipped value gains one …)
sampleRate 1 Share of errors that get a replay segment
mask / unmask / block / ignore [] Selector-level privacy, below
maskFn none Last transformation over values leaving unmasked
remoteConfig true Read the project's stricter-only replay settings at init
sessionSampleRate 0 Share of sessions recorded whole, error or no error (below)
sessionIdleTimeoutMs / sessionMaxDurationMs 15 min / 60 min When a recorded session ends
sessionFlushIntervalMs 10000 How often a recorded session uploads
networkDetailAllowUrls [] URLs whose headers and bodies are captured (below)
networkRequestHeaders / networkResponseHeaders [] Header names captured for those URLs
networkCaptureBodies true Bodies of allowlisted requests
consoleLevels ['error', 'warn'] Console methods recorded
deadClicks / deadClickTimeoutMs true / 7000 Mark clicks that change nothing
vitals true LCP, FCP, TTFB, CLS and INP marks
minSegmentIntervalMs 5000 Minimum gap between uploaded segments
windowMs / maxEvents 30s / 200 Ring buffer bounds — how far back and how much
console / fetch / xhr / history / dom true Per-source capture toggles
rageClickThreshold / rageClickWindowMs 3 / 1000 Rage-click detection
maxOverheadRatio 0.02 Recorder disables itself past this share of wall time

Masking beyond maskAllText cannot be turned off: type="password", autocomplete credential tokens, and name/id/aria-label patterns matching password/token/cvv/ssn/… shapes are always redacted. The explicit opt-out is the data-bucker-mask attribute (also data-private, data-sentry-mask), which hides a whole subtree, not just the element carrying it. See replay-privacy.md for the full capture-to-storage pipeline, including what reaches the server and where server-side scrubbing happens.

Web vitals

@bucker/browser/web-vitals measures the Core Web Vitals of each page view from the user's own browser:

import { init } from '@bucker/browser'
import { webVitals } from '@bucker/browser/web-vitals'

init({ dsn, tracesSampleRate: 0.2 })
webVitals()

When the page is first hidden (the user switches tab, navigates away or closes it), it sends one span named pageload <page>, starting at the navigation, with these attributes:

Attribute Meaning Unit
web_vital.lcp Largest Contentful Paint ms
web_vital.inp Interaction to Next Paint: the slowest interaction, ignoring one per 50 ms
web_vital.cls Cumulative Layout Shift: the largest burst of layout shifts none
web_vital.fcp First Contentful Paint ms
web_vital.ttfb Time to First Byte ms
browser.page the page, with id-like path segments replaced (/orders/:id)
bucker.op pageload

A vital the browser did not report is left out, not sent as 0. Safari reports no LCP or INP, and a page nobody clicked has no INP. The span is sampled like any other, so set tracesSampleRate (or tracesSampler); with tracing off nothing is sent. Pass pageName: () => myRouter.currentRoutePattern to name pages by your router's routes instead of by path.

With session replay on, pass the replay's id so the player marks LCP, FCP and TTFB on the replay's timeline:

const replay = replayIntegration()
init({ dsn, tracesSampleRate: 0.2, integrations: [...defaultIntegrations(), replay] })
webVitals({ replayId: () => replay.replayId })

The Web vitals dashboard template shows p75 of each vital, overall and per page (see dashboards.md). The vitals are ordinary span attributes, so Explore and span alert rules can use them too (for example, p75 of web_vital.lcp where bucker.op is pageload).

Finding replays

Explore › Replays lists every recorded session in the project, one row per session, with its first page, duration, pages visited, errors, rage clicks, dead clicks, browser and release. The search uses the same grammar as the issue stream:

Key Matches
user: The id, email or username your code set on the scope. It is matched by its hash; the identity itself is never stored
url: Any page template the session visited, * as a wildcard (url:/checkout*)
browser: / release: / environment: browser:firefox*, release:web@2.*
errors: / rage_clicks: / dead_clicks: / failed_requests: Counts, with >, >=, <, <= (errors:>0)
duration: Seconds (duration:>60)
started: A date or a relative time (started:-24h)
is:session / is:error Recorded whole, or with an error captured
has:user / has:issue / has:release The field is present

Free text matches a page, the browser or the release. The query is kept in the URL, so a filtered list is a link you can paste into a ticket. The player shows chapters, one per navigation, headed by the page and counted: actions, errors, rage and dead clicks. They are computed from the recording, with no generated text. Copy link at 0:42 copies a link that opens the same recording at the same moment (?segment= and ?t= on the page's URL), from the issue's Replay tab or the standalone player. The Network pane draws every request as a waterfall bar on one scale, failed requests outlined. Click a row to seek to it, and unfold its headers and body when network detail was captured. To make user: work, set the user on the scope (setUser({ id })) before errors happen. A replay that has no user of its own takes the user of the error it is linked to.

Recording whole sessions

sessionSampleRate (default 0, off) records that share of sessions in full, error or no error, for UX problems that never throw: a confusing flow, a dead end, a form people abandon. A sampled session uploads a segment every sessionFlushIntervalMs (default 10 s), when an error is captured (stamped with its id, so it links to the issue), and when the tab is hidden for good (pagehide, through the beacon-aware transport). An unsampled session keeps error-triggered replay exactly as above.

replayIntegration({ sessionSampleRate: 0.05 }) // 5% of sessions, recorded whole

The session lives in a first-party session cookie, bucker_replay, so it continues across page loads in the same tab and is sampled once rather than on every navigation. It ends after sessionIdleTimeoutMs (default 15 minutes) without activity, and the next activity starts a new one. After sessionMaxDurationMs (default 60 minutes) the tab goes back to error-only replay until the next session. Session segments are billed in the same replay unit as error segments. The project's Session recording rate ceiling can lower this rate remotely and never raise it.

Masking by selector

Four selector lists refine maskAllText. Each matches the element and its ancestors, so a selector on a container covers its whole subtree:

Option Effect
mask Text and values inside are masked even with maskAllText: false
unmask Under the default maskAllText: true, values inside are captured in the clear. Credential-shaped fields stay masked whatever this says
block The subtree is opaque: a click or input inside it is recorded against the blocked element, with no label and no child selector
ignore Clicks and input inside are not recorded at all
replayIntegration({
  unmask: ['#search'],
  mask: ['.customer-name'],
  block: ['#support-chat'],
  // Runs on every value about to leave the page UNMASKED, and can only remove from it.
  maskFn: (text) => text.replace(/\d(?=\d{4})/g, '*'),
})

An invalid selector matches nothing. A maskFn that throws masks the value.

Network detail, console levels, dead clicks and vitals

By default a request is recorded as method, URL template, status and timing, and nothing else. To capture headers and bodies, name the URLs and the headers:

replayIntegration({
  networkDetailAllowUrls: ['/api/checkout', /\/api\/orders\//], // matched against the raw URL
  networkRequestHeaders: ['content-type'],
  networkResponseHeaders: ['x-request-id'],
  networkCaptureBodies: true, // default; false keeps it to headers
})

For an allowlisted URL, headers are captured by name only. authorization, cookie, set-cookie, x-api-key and other credential headers are dropped even when named. A JSON body has its credential-shaped keys replaced with <masked>, and every body is cut at 2048 characters. The response body is read from a clone after your code has the response, so it never delays your own read. The organization's scrub rules run over all of it before it is stored. A project that enforces masking switches network detail off, because a body is page content.

consoleLevels (default ['error', 'warn']) widens console capture to info, log or debug, still masked like any other console message.

A click followed by no DOM change and no navigation within deadClickTimeoutMs (default 7000) is marked dead: the button that looks clickable and does nothing. Clicks into fields are never marked. deadClicks: false turns this off.

LCP, FCP, TTFB, CLS and INP are recorded as numbers at the moment the browser reports them, and appear as marks on the replay timeline. No element or URL is attached. vitals: false turns this off.

Replays linked to backend traces

A request that carries a W3C traceparent header is recorded with its trace and span ids, and so is one whose response carries a traceresponse. Ids only, no other header. The player's Traces pane then opens that trace's waterfall and its logs, lists the backend errors on the same trace, and marks them on the scrub bar. Errors from projects the reader cannot open are left out. The recorder does not add the header itself: adding a header to your requests changes their CORS preflight, so propagation stays your decision. To propagate from the browser, add the header where you make requests:

import { getTraceHeaders } from '@bucker/sdk-core/tracing'

fetch('/api/checkout', { method: 'POST', headers: { ...getTraceHeaders() }, body })

Remote configuration

At init the integration reads the project's replay settings from GET /api/<projectId>/replay-config (DSN-authenticated) and caches them for an hour. They can only make recording stricter than your code: they can force maskAllText on, add mask/block/ignore selectors, revoke unmask, and cap sampleRate. They can never turn masking off or raise a rate. On a first visit, recording waits for the response (at most 3 seconds) so nothing is captured under a looser rule. If the fetch fails, your code's own configuration applies. Set remoteConfig: false to skip the request.

The settings live in Settings › Projects › Session replay. Enforce masking is also checked at ingest: while it is on, a recording that arrives unmasked is refused and nothing is stored, whatever the SDK sent.

Not built yet

The breadcrumb DSL's richer compaction is not implemented. Local-variable capture is Node-only in design and not implemented there either — see sdk-node.md.