Beacon

Project ID for tracking (same as pixel data-project-id)

Who the visitor is, when the page already knows at construction time. When identity only becomes known later (a login part-way through the session), call identify() instead.

Where batches are POSTed. Defaults to the hosted ingest endpoint declared in NETWORK_CONTRACT.md.

Set it to send somewhere else — a self-hosted deployment, a regional install, or a test origin. An override means the destination is the integrator's, not ours, so NETWORK_CONTRACT.md describes the DEFAULT and says so explicitly.

Optional environment tag for data segmentation

Optional tags for custom data segmentation

Not read by the SDK. Construct the beacon only when it should run, and call destroy() to stop it.

Verbose console logging.

Log verbosity.

When the browser sends Do Not Track, the beacon collects and sends nothing.

Truncate the stored IP to /24 (IPv4) or /48 (IPv6) before persistence.

Strip the #fragment from the url/referrer collector fields before they leave the page. Defaults to true: a fragment is never sent to the server by the browser in the first place for any OTHER surface (it is script-visible only), so a beacon that forwards it is the one place it can leak — and it is also the highest-risk part of the URL, since SPA routers, magic-link auth, and OAuth implicit-flow responses all put tokens there. Set to false only if a project genuinely consumes url's fragment server-side.

Query parameter names (matched case-insensitively) to redact from the url/referrer collector fields before they leave the page. Each matching value is replaced with the literal string "[redacted]"; the parameter itself stays present so the URL's shape is unchanged. Empty by default — nothing is scrubbed unless a project opts in with the param names it puts tokens/PII behind (e.g. ["token", "email"]). Ignored for a parameter when dropQueryParams is also true, since there is no query string left to scrub.

Drop the entire query string from the url/referrer collector fields before they leave the page. Off by default. Takes priority over scrubQueryParams when both are set — there is nothing left to scrub once the whole query string is gone.

Inactivity timeout in milliseconds (30 minutes). Every send extends it, so the session cookie rotates only after that much idle time.

Name of the visitor session cookie shared by pixel, beacon, gateway, and SDK rows. Query it with ?sessionId= on the detections endpoint.

Resume a browser session id the page stored earlier (a receipt's browserSessionId, see onReceipt) instead of reading the session cookie or minting a new id. With cookies off this is the only way two page loads stay one session, and a posture token verifies only against the session id it was issued to. 1 to 255 characters of A-Z a-z 0-9 . _ ~ -; anything else is ignored with a warning. updateConfig({ browserSessionId }) switches a running beacon to it.

Called with every ingest receipt: the server's session id, the browser session id the batch was sent under, and the posture token or the reason there is none. Runs on the main thread in worker mode too, after the posture cookie write. An error it throws is logged at warn and never affects delivery.

How much keyDwellCount + pressCount + untrustedEvents has to grow, as a multiple of its value at the last send, before an interaction sends again. 2 sends at 1, 2, 4, 8, 16 samples; 1.5 sends more often, 3 less. A value at or below 1 falls back to the default.

Fraction of the posture token's lifetime after which a counted interaction sends again, so the token stays fresh under a live hand. 0.5 refreshes the 120 s token once an interaction lands more than 60 s after the last send. A value outside (0, 1] falls back to the default.

Which automatic sends fire. Every trigger is on unless set to false. Turning unload off leaves trackPageUnload() available for a host that wires its own listener; turning arrival off leaves collect().

Low-frequency backstop that refreshes posture on a jittered timer, independent of interaction, so a visitor who goes idle past the posture TTL with no counted interaction is not one stale click on a critical action away from an expired token (H0BB5, PR #5095 review). The actual interval on each tick is proactiveRefreshMinIntervalMs plus a random [0, max - min) jitter, so a fleet of clients loaded at the same moment does not all refresh on the same wall-clock boundary. Paused while the page is hidden, resumed on visibilitychange. Gated by triggers.posture, the same switch that already turns off the interaction-triggered staleness check — this timer is that same 'posture' trigger firing proactively, not a second mechanism. A non-positive value falls back to the default.

The upper bound of the proactive-refresh jitter window; see proactiveRefreshMinIntervalMs. A non-positive value falls back to the default; a value below proactiveRefreshMinIntervalMs degrades to the minimum on every tick rather than throwing.

How old the last send must be, in milliseconds, before a visibility resume forces an immediate posture refresh. Defaults to the same threshold the interaction-triggered check already uses (postureRefreshFraction of the posture token's lifetime), so the two stay in lockstep unless a host deliberately wants the visibility check to be stricter or looser. A non-positive value falls back to that default.

On visibilitychange back to visible, force an immediate posture refresh when it is stale (see proactiveRefreshFreshnessMs); a fresh tab regaining focus does not get an unnecessary send either way. Set to false to leave visibility resume to the plain interval alone.

Refresh posture (and drain anything the offline queue is still holding) when the browser fires online. Set to false to leave reconnection recovery to the offline queue's own online listener alone.

A fixed seed for the proactive-refresh jitter roll, for deterministic tests. Omit in production for real Math.random() jitter.

Per-collector deadline in milliseconds. A collector still running past this deadline is dropped from the current collection round rather than awaited further — see collectWithDeadline in checkpoint-beacon. Default and rationale documented in checkpoint-beacon's src/budget/thresholds.ts.

Maximum number of queued events.

Retry count for failed sends.

Base retry delay in milliseconds.

Delays in milliseconds between posture-recovery attempts after a durably-queued ingest response that carried no posture verdict. The array's length is the attempt ceiling. Defaults to the shipped ladder; override only in tests and in a self-hosted deployment with a different outage profile.

Prefer a Web Worker for event processing, batching, and transport. Page-dependent collection remains on the main thread. Unsupported browsers fall back to the main thread; SSR never starts a worker. Set false to disable the processing worker.

Alias for useWorker, accepted for callers using the older option name. When both are set, useWorker wins — see resolveUseWorker.

URL of the worker script (beacon.worker.js, exported as @kya-os/checkpoint-beacon/worker). Classic workers must be same-origin. When unset, the beacon derives beacon.worker.js next to the <script> tag that loaded beacon.min.js, else /beacon.worker.js at the site root.

Worker lifecycle tuning: initTimeoutMs (3000), messageTimeout (30000), heartbeatInterval (5000), maxRetries (3), retryDelay (1000), compressionThreshold (5120), allowFallback (true).

Explicit URL override for the lazy-loaded signals chunk (beacon-lazy-signals.min.js — userAgentData, fontPreferences, Client Hints, webrtcCodecs, speechVoices, plus canvas/WebGL/audio/permissions render entropy). Same shape and purpose as workerUrl: when unset, checkpoint-beacon derives the chunk's URL from wherever beacon.min.js itself was loaded from — see checkpoint-beacon's src/core/load-lazy-chunk.ts for the full resolution order.