Beacon reference
Look up every Beacon method, session and receipt rule, data collection detail, posture verification step, delivery behavior, CSP directive, and browser requirement.
To install the Beacon and send your first event, start with Beacon setup.
How it works
When the beacon sends
Every send is a full snapshot of what the page has observed so far. Each automatic send is tagged with the reason it fired (metadata.trigger). trackEvent() is tagged custom, and your own collect() carries no tag. Only one automatic send runs at a time, and triggers that arrive while one is in flight collapse into a single follow-up. The page-hide send and your own collect() and trackEvent() calls are not queued behind it.
There is no fixed-interval heartbeat, and nothing on the client suppresses the arrival send of a new full page load. A visible tab that sits idle still sends about once every 60 to 120 seconds through the posture timer, whether or not the project uses browser posture. Turn that off with triggers: { posture: false }, but that also turns off every posture refresh: the token lives 120 seconds, so once the page stops sending for other reasons, enforcement has no fresh posture after about two minutes. Do Not Track, destroy(), and the hosted script's Shopify consent gate apply to every row above. Each trigger's switch is in Tuning dispatch.
The last two rows are on by default. Turn them off with the navigation trigger:
const beacon = new CheckpointBeacon({
projectId: '<project UUID>',
triggers: { navigation: false },
});Already calling collect('pageview') on route changes? From 1.4.3 the beacon records soft
navigations itself, so every route change sends twice. Set triggers: { navigation: false }, or
remove your own call. The hosted script has no such call to remove.
Beacon API
new CheckpointBeacon(config)
Creates a beacon, wires the evidence-dispatch triggers, and sends one automatic pageview. Throws when config.projectId is missing or empty. Every other option has a default.
collect(eventType?)
Runs a collection round and sends one event immediately. eventType defaults to 'pageview'. The valid types are 'pageview', 'pageunload', 'evidence', 'heartbeat', 'custom', 'error', and 'performance'. The SDK doesn't produce 'heartbeat' on its own; the type stays for direct calls and already-deployed bundles.
Returns a promise that resolves once the send completes, ingest round trip included, so the posture cookie (when the server issues one) exists by then. Under Do Not Track it resolves without doing anything.
await beacon.collect('pageview');trackEvent(name, metadata?)
Sends a custom event. Metadata must be JSON-serializable. The beacon spreads it into the event envelope, then sets eventName, sessionId, timestamp, and identity, so those four keys cannot be overridden.
await beacon.trackEvent('button_click', {
buttonId: 'signup-cta',
page: '/home',
});The event name and your metadata travel with the event and pass validation, but the ingest
endpoint currently persists only the event type, the session id, and the identified user id from
the envelope. Custom metadata does not appear in the dashboard today. Use trackEvent() to add a
detection sample at a meaningful moment, not to store your own attributes.
prepareForAction({ action, maxPostureAgeMs?, maxWaitMs? })
Refreshes posture evidence and returns a promise that resolves once the beacon holds a usable posture token. It resolves at the first of these: a token is held (an unexpired token counts, even one older than maxPostureAgeMs), maxWaitMs has elapsed (default 3,000), or posture is withheld or switched off. Withheld means ingest refused a token for a terminal reason such as domain-unset or origin-mismatch. Switched off means Do Not Track is on or the beacon was destroyed. The promise never rejects, so an await needs no try.
The refresh it starts is a no-op when posture is already fresh (age under maxPostureAgeMs, default 30 seconds), a refresh is in flight or settled too recently, or the beacon is already retrying a pending posture. Calling it on every keystroke or pointer move costs at most one request.
On a first visit, a page's first token arrives only after the first beacon request returns. A call to your API made before then carries no token and is reported absent. Await prepareForAction before that call. Once a token exists the await resolves at once, so later calls pay nothing. maxWaitMs is limited to 0 through 10,000; a value outside that range is clamped, and a value that is not a finite number uses the 3,000 default:
generateButton.addEventListener('focus', () => {
checkpoint.prepareForAction({ action: 'image_generate', maxPostureAgeMs: 30_000 });
});
async function onGenerateClick() {
await checkpoint.prepareForAction({ action: 'image_generate', maxPostureAgeMs: 30_000 });
await callImageGenerate();
}A call that does not await still works and sends whatever token is on hand. Where a call must never be held, such as a latency-bound action, keep prepareForAction fire-and-forget at the moment of intent and do not await it. The hosted script's checkpointFetch waits for you: until the page has held its first token it waits up to 3 seconds for one. If that wait ends with no token, later calls do not wait again.
The wait is bounded. The promise resolves after maxWaitMs even when no token arrives, so the
protected action always runs. Lower maxWaitMs where holding that action for up to 3 seconds is
too long.
identify(identity?)
Tells the beacon who the visitor is once your site knows. Pass { userId }, your own id for the signed-in user, up to 255 characters. Longer values are rejected at ingest. Every later event carries it as metadata.identity.userId, and it is stored as the detection's user id. Earlier events in the session stay anonymous.
Call it with no argument on sign-out, so a shared device stops attributing the next visitor's activity to the person who left. That call also starts a new session, and so does passing a different userId than the one the session already has. If the identity is known at render, pass identity in the constructor instead.
beacon.identify({ userId: 'user_123' });
beacon.identify();handoffUrl(url)
Resolves with url plus a single-use checkpoint_handoff token bound to your project and the current session. Put the result in an email, a QR code, or a link to another domain that runs the same project's beacon or pixel. The landing page sends the token with its first event, Vouched KYA continues the original session there, and the page strips the parameter from the address bar.
const link = await beacon.handoffUrl('https://shop.example.com/cart');The token is an opaque random value that Vouched KYA stores for 15 minutes, and it works once: the first page to redeem it continues the session. Vouched KYA issues a token only for a session it has seen, so the request carries the nonce from the session's latest response (valid for 10 minutes). A session can be adopted at most twice, one issuing device can hand off to at most three distinct devices in the 30 days after its first handoff, and one verified network and user agent can hand off to at most 20 distinct devices per hour, not counting redeemers on the same network and user agent as the issuer. A repeat use by the same redeemer within 15 minutes of the redemption returns the same session; any other later use starts a fresh session. A redemption without a device id, or with the all-zero or all-f placeholder id that unrelated visitors share, is rejected before the token is read: the token is not spent and nothing is counted, and the landing page keeps its own session and latch. A visitor with Do Not Track or blocked storage sends no device id, so it never adopts. The promise resolves with the URL unchanged, without a network call, when cookies are not allowed (Do Not Track) and when there is no nonce yet. It also resolves with the URL unchanged, after the request, when Vouched KYA cannot issue a token. With Do Not Track on the beacon removes the parameter and never redeems it. When Vouched KYA could not reach its handoff state in time (handoff.status is unavailable) the parameter stays and the next batch retries, up to three attempts; after the third the beacon drops the token and removes the parameter. The response is applied only if the session did not change in the meantime. The beacon removes the parameter from the url and referrer it sends. If the destination is identified as a different user than the one who made the link, Vouched KYA answers rejected, the page keeps its own session and the token stays unspent; an anonymous destination records the issuing user on the adopted session.
getSessionId()
Returns the client session id the beacon stamps on every event. It is a pure read: it doesn't extend the session or touch the cookie, so polling it from a status footer is safe. The server assigns its own consolidated session id (see Sessions).
getPostureHeaders()
Returns the two request headers a backend needs to read the session's posture verdict, as a plain object. It is a pure read: no network call, no storage write, and it doesn't extend the session.
An idle session returns {}. When the session changes, headers use the new id and omit the old token. A late receipt for an earlier session cannot replace the current token. For the same binding, the newer issue time wins, and a later clean token doesn't replace an agent-driven one while that one is unexpired. On HTTPS, an unexpired token is restored from session storage on reload only for the same project, origin, and browser session. This cache delivers the credential; the receiving SDK still verifies its signature and binding. When Do Not Track blocks collection, the beacon clears the cache. Destroying the last beacon clears its in-memory token but keeps the reload cache until it expires. See Sending posture to another host.
const headers = beacon.getPostureHeaders();getRequestProofHeader(request)
Signs a proof that this browser holds the beacon's key, for one outgoing request. request is { method, url }. It returns a promise for the signed proof string. When the browser reports Do Not Track it resolves to undefined and signs nothing, whatever respectDoNotTrack is set to.
The key pair is a non-extractable P-256 pair. The beacon creates it on first use and keeps it in IndexedDB for the browser profile. Every call signs a new proof. The signing time is the browser's clock corrected by the Date header of the latest ingest response, so a browser clock that is minutes off still lands inside the ingest's 60-second freshness window once one response has arrived. Until then it is the browser's own time, and a Date header more than 24 hours from the browser clock is ignored. If signing fails, for example when WebCrypto is unavailable, the promise rejects and your code decides what to do.
const proof = await beacon.getRequestProofHeader({
method: 'POST',
url: 'https://api.example.com/generate',
});trackPageUnload()
Records a pageunload event through the Unload path in How it works. Calling it from a pagehide handler is optional and safe (see Quick start).
updateConfig(updates)
Merges configuration at runtime.
- Changing
useWorker,enableWebWorker,workerUrl, orworkerConfigrestarts the worker. - Setting
browserSessionIdmoves the next send onto that session. flushIntervalandbatchSizeare accepted and ignored (deprecated no-ops).- Setting
respectDoNotTrack: truefor a DNT visitor mid-session releases the interaction listeners and evidence-dispatch triggers, expires the_as_beacon_sessioncookie and thecheckpoint_userandagentshield_useridentity cookies, and starts a new in-memory session id. Setting it back re-wires them under that new id, so a consent manager can drive it. It also discards events still held in memory, in the worker as well, so nothing queued is sent after the flip.
The options it cannot change are in the read-once callout under Configuration options.
beacon.updateConfig({ respectDoNotTrack: false });addCollector(collector)
Registers an extra collector for a signal the default set doesn't carry. A collector implements ICollector (exported from the package): type, enabled, unloadSafe, isSupported(), collect(), and optional start() and dispose(). A second instance of an already registered class is refused with a warning. When two collectors write the same key, the first writer wins and the collision is logged.
destroy()
Removes the visibilitychange/pagehide listeners and the counted-interaction callback, disposes every collector (removing its listeners), terminates the worker, and drains the offline queue.
beacon.destroy();The Beacon is not an event emitter: there is no .on(...), no client-side detection event,
and no start(), stop(), or getDetectionResult() method.
More than one beacon on a page
A tag manager, a framework wrapper, and a hand-written snippet can each construct a beacon on the same page. Beacons that share a projectId share one running beacon. The second new CheckpointBeacon(...) attaches to the first and returns a handle to it. The handle's prototype is CheckpointBeacon.prototype, so instanceof is true.
The page gets one arrival pageview, one worker, one set of dispatch timers, and one DPoP key. Every method on the handle calls the shared beacon, so getSessionId() and getPostureHeaders() return the same values from either.
The match is on projectId character for character. acme-corp and the project's UUID are different keys even for the same project, so two beacons built with them run separately and each sends its own pageview. Use one id everywhere; the UUID is the form we recommend. Only copies that carry this behavior attach to each other, and an older release on the same page runs on its own.
When the second beacon's config differs from the first's:
How the privacy settings combine:
updateConfig on a handle follows the same rules, and a destroyed handle's updateConfig is ignored.
Sessions
The beacon keys every event to a visitor session stored in a first-party cookie, _as_beacon_session by default (sessionCookieName).
Receipts and resuming a session
onReceipt is called on the main thread for every 202 ingest response, in worker mode too, right after the beacon stores the posture cookie. It receives a BeaconReceipt:
An error thrown inside onReceipt is logged at warn and never affects delivery.
To keep one session across page loads without cookies, store browserSessionId wherever the page keeps state and pass it back at construction:
const beacon = new CheckpointBeacon({
projectId: '<project UUID>',
browserSessionId: loadStoredBrowserSessionId(),
onReceipt: ({ sessionId, browserSessionId, posture }) => {
saveBrowserSessionId(browserSessionId);
if (sessionId) recordCheckpointSession(sessionId);
if (posture) latestPosture = posture.token;
},
});loadStoredBrowserSessionId() returns undefined on a first visit. recordCheckpointSession() stands for your own code, which joins your record to the visit.
The option takes 1 to 255 characters of A-Z a-z 0-9 . _ ~ -. Anything else is ignored with a warning. The resumed id still ends after the idle gap, like any other. updateConfig({ browserSessionId }) switches a running beacon to a stored id, for a page that loads it after construction.
Data collection
Five collectors run on every collection round:
The fingerprint and lazy collectors are marked unsafe during unload and are skipped on the pageunload path.
The lazy chunk is injected as a <script> at low fetch priority after window.load and an idle period, and only when its URL can be resolved. The URL comes from lazySignalsUrl, otherwise from next to wherever beacon.min.js was loaded from, whatever the file is called. The script tag install needs no setup. A bundler does: see Self-host the companion files.
What leaves the page, alongside the signals above:
Redaction runs client-side, at collection time, before url and referrer are placed on the event. URL redaction and IP truncation (anonymizeIp, which stores only a /24 (IPv4) or /48 (IPv6) prefix) require @kya-os/checkpoint-beacon 1.2.0 or later. The defaults described here (query values and path segments redacted, anonymizeIp on; set it to false to keep the full address) apply from the first release after 1.4.3. The package declares its full data inventory in a network contract, and a test asserts the SDK's real network behavior against it.
Do Not Track
When navigator.doNotTrack (or the window.doNotTrack and msDoNotTrack variants) reads 1 or yes and respectDoNotTrack is on (the default), the beacon collects and sends nothing. collect(), trackEvent(), and trackPageUnload() return immediately, no automatic arrival send happens, and the interaction listeners and evidence-dispatch triggers are never attached. Global Privacy Control is not read.
The session cookie for a Do Not Track visitor depends on the release:
The stored DPoP keypair and its sent marker are not cleared, and neither is a posture cookie already stored, which expires by itself within its 120 second lifetime. The nonce keys and the offline queue are removed, and events still queued in memory, in the worker as well, are discarded, so nothing queued is sent after the flip.
Consent
The beacon withholds nothing on consent. requireConsent, grantConsent() and the script tag's data-require-consent are accepted and ignored, so existing installs and typed configs keep working (the first use on a page logs one console.warn saying so), and the hosted loader starts the beacon on every load except on a Shopify storefront, where Shopify's Customer Privacy API is still honored (below). Only Do Not Track (respectDoNotTrack) stops collection everywhere else. Storage the browser blocks only removes what would be stored: no device id is sent and the session id lives in memory.
On a Shopify storefront the hosted script constructs nothing, sends nothing and writes no identity cookie until Shopify reports that analytics processing is allowed (consent given, or not required in the visitor's region). It reads the answer on load and listens for visitorConsentCollected. When the answer is not allowed, at load or later, it destroys the beacon and expires checkpoint_user, agentshield_user and the _as_beacon_session cookie, and removes the project's stored nonces and the stored offline queue, so a later grant in the same page view starts a fresh beacon with a new session. The loader starts nothing when Shopify's API cannot be read.
CheckpointBeacon.clearIdentity() expires checkpoint_user and agentshield_user on request, for a page that wants to forget the device. Passing the project id, CheckpointBeacon.clearIdentity(projectId), also expires the default-named _as_beacon_session cookie, removes every stored nonce whose key starts with that project id (so a project whose id extends it loses its nonces too, and the server tags its next batch as having no nonce) and deletes the whole stored offline queue for the origin, which is shared by every beacon there. A beacon that was destroyed before the clear no longer writes failed sends to the stored queue, so a send that fails after a withdrawal cannot bring the old session back; a plain destroy() still keeps its stored retries. The Java SDK reads those cookies on the server, so it stops reporting the id once the browser stops sending them.
Cookies the beacon writes
When ingest withholds a token, the 202 body says why in postureStatus, visible in the browser's network inspector on every build. The npm build also logs it once per reason at warn when logLevel allows.
A withheld token never drops the visit: the detection is still recorded.
From 1.4.3 a withheld reason on a queued receipt ends the ladder too. Earlier releases kept retrying on any queued receipt without a token.
Verifying the posture token
The posture token lets your server read the session's verdict without calling Vouched KYA. The server SDKs (Java, .NET, Express, Next.js) verify it for you once browser posture is configured. Any other stack can verify the JWS directly.
A project's key id changes only when its key is rotated. Rotation publishes the next key in keys
before it is used and keeps the retiring key there until its tokens expire. A server that reads
the keys endpoint instead of pinning, such as a Java server configured with
BrowserPostureOptions.remoteKeys, picks the change up on its own within about two minutes. A
server that pinned one key must take the new one.
detection is { "class": "ai_agent" | "bot", "name": string, "confidence": integer }: the beacon's final verdict for the session, present only when that verdict is an agent or a bot. name is 1 to 64 characters with no control characters and confidence is 0 to 100. The beacon keeps it on later tokens for the session for 30 minutes, so a batch without the evidence does not drop it. A detection that is present but malformed makes the whole token invalid. Readers that predate the claim ignore it.
network is { "timezone"?, "languages"?, "rtt_ms"?, "serving_region"? }: what the browser reported about its own network path, present when it reported any of it. timezone is the IANA time zone name, languages is up to five language tags, rtt_ms is a round trip of the beacon's own requests in milliseconds, and serving_region is a string. The browser reports these values and Vouched KYA does not verify them. Readers that predate the claim ignore it.
When a verified token carries detection, the Express and Next.js SDKs reclassify a request their own engine called human or incomplete data as that agent or bot. Without it they apply automation_disclosed (a bot named Automation Tools at confidence 80), then automation_corroborated (incomplete data at confidence 40), then an agent-driven verdict. They never downgrade an agent or bot the engine already found.
Check the signature and kid against the pinned key, then typ, iss, aud, exp, and origin. Check that binding is the hex SHA-256 of the visitor's browser session id: the _as_beacon_session value, or the receipt's browserSessionId when cookies are blocked.
Treat a missing or invalid token as no evidence, never as a reason to allow.
Sending posture to another host
Both cookies are host-only. If the protected request goes to another host, such as an API subdomain, neither cookie goes with it. Attach the headers yourself with getPostureHeaders(). Call it when dispatching each request to an API you control, and replace any older posture headers. It reads the current receipt without waiting for collection or refresh, so it also works when cookies are blocked. Do not cache its result as client-wide defaults.
const beacon = new CheckpointBeacon({ projectId: '<project UUID>' });
await fetch('https://api.example.com/generate', {
method: 'POST',
headers: { ...beacon.getPostureHeaders() },
});The Java, .NET, Express, and Next.js server SDKs read these two headers, and each one wins over its cookie. A header sent twice is ignored rather than guessed at. For a cross-origin request, add the posture headers to the API's existing CORS allow list. Proof flows also need DPoP and the exposed challenge headers:
Access-Control-Allow-Headers: KYA-Posture, KYA-Posture-Session, DPoP
Access-Control-Expose-Headers: DPoP-Nonce, WWW-AuthenticateA token lives for 120 seconds. Background refresh replaces it while the session is active, without extending the session's idle deadline. A first visit still needs the first server response before a signed token exists. On HTTPS reloads, the beacon can immediately reuse an unexpired token cached for the same project and session. If renewal fails or a hidden page's token expires, getPostureHeaders() omits KYA-Posture; it also omits KYA-Posture-Session after the session's idle deadline. Missing posture stays unknown, and a token with insufficient observations does not establish human traffic. Await prepareForAction shortly before a protected action to request a refresh and wait, up to maxWaitMs, for the token. Once the receipt arrives, the next header read includes the new token.
Web Worker mode
Worker mode is on by default in a capable browser. Turn it off with useWorker: false (or the enableWebWorker: false alias). Network requests run in the worker. Collection always stays on the main thread.
For a bundled install, set workerUrl to the companion worker copied from the installed package onto your own origin. There is no script tag from which to derive its URL. The hosted script can also fetch its matching worker from another origin, verify the embedded integrity hash, and start it from a blob: URL. That path needs worker-src blob:; a blocked or failed worker falls back to the main thread.
const beacon = new CheckpointBeacon({
projectId: '<project UUID>',
useWorker: true,
workerUrl: '/static/beacon.worker.js',
});workerConfig tunes the manager:
A Content Security Policy whose worker-src (or script-src) excludes the worker URL blocks creation, and the beacon falls back. A workerUrl on another origin is fetched with the hash built into the beacon as its integrity and started from a blob: URL on the page's origin, so it needs connect-src for its host and worker-src blob:. For advanced setups, the BeaconWorkerClient class is exported from @kya-os/checkpoint-beacon.
Tuning dispatch
Three settings shape the automatic sends, plus a low-frequency backstop timer that only ever refreshes posture. None of them brings back a fixed-interval heartbeat.
With unload: false, trackPageUnload() still works for a listener you wire yourself. With arrival: false, call collect('pageview') yourself, and whatever has not been delivered still leaves on unload.
const beacon = new CheckpointBeacon({
projectId: '<project UUID>',
evidenceGrowthFactor: 3,
postureRefreshFraction: 0.25,
triggers: { signals: false },
proactiveRefreshMinIntervalMs: 45000,
proactiveRefreshMaxIntervalMs: 90000,
});Delivery: retries and offline
Network & CSP
Every batch is a POST to https://kya.vouched.id/api/v1/beacon (override it with endpoint), with Content-Type and X-Project-ID headers, plus X-Content-Encoding: gzip-base64 when compressed, and KYA-Posture-Proof (a signed proof from the page's key, for the ingest to bind the stored posture answer to this browser) on non-critical fetch batches when signing succeeds, unless Do Not Track is on, the key store stalled earlier on the page (proofs then stay off for the rest of the page), or the endpoint refused the header on two consecutive batches before the page had once sent it successfully. Those headers mean every request is preflighted with OPTIONS. The endpoint answers with Access-Control-Allow-Origin: *.
From 1.4.3, onReceipt hands a 202's sessionId, posture, and postureStatus to your page (Receipts).
If your site restricts outbound requests (a Content Security Policy, a corporate proxy, or tracker blockers), allow these. The connect-src policy to copy is in Content Security Policy.
A policy with default-src also reports a style-src-attr violation from a fingerprint probe, which costs no signal. Releases before 1.4.3 also reported a worker-src violation for each blob: worker their capability probe started (one from the lazy chunk, and a second unless useWorker is off). From 1.4.3 the probe starts no worker. A worker fetched from another origin and started through the verified blob path needs worker-src blob:.
A Content-Security-Policy on your HTML page does not restrict a worker the beacon starts from an http: or https: URL (workerUrl, or beacon.worker.js beside the script). That worker takes the policy of its own script response, so your page's worker-src and script-src decide only whether it starts. A worker started through the verified blob path inherits the page's policy. If your server or CDN adds a policy to JavaScript responses, a connect-src or default-src on the beacon.worker.js response that omits the ingest host blocks the worker's requests: allow the host, or 'self' with the first-party proxy.
Self-host the companion files
By default the beacon looks for beacon-lazy-signals.min.js and beacon.worker.js next to the beacon.min.js tag that loaded it. A bundled install has no such tag, so the worker and the lazy signals never load. Host both files yourself, name each one, and copy them from the dist/ of the installed package:
const beacon = new CheckpointBeacon({
projectId: '<project UUID>',
lazySignalsUrl: '/static/checkpoint/beacon-lazy-signals.min.js',
workerUrl: '/static/checkpoint/beacon.worker.js',
});- Copy both files from the exact package version your application imports, or the pinned version of
beacon.min.js. Repeat the copy when updating the dependency. A mismatched chunk fails the integrity check. - The worker must be same-origin. Pass a same-origin
workerUrl, or setuseWorker: false. Otherwise the worker can't start and the beacon uses the main thread. - Without
lazySignalsUrl, a bundled install never collects the 22 lazy signals. The chunk is also exported as@kya-os/checkpoint-beacon/lazy-signals.
lazySignalsUrl is read once at construction (Configuration options). A chunk on another origin must send Access-Control-Allow-Origin (CORS); a same-origin file needs nothing extra. Allow the chunk's host in script-src and the worker's origin in worker-src (see Network & CSP).
Integrity check on the lazy chunk
beacon.min.js and the npm build embed the SHA-384 hash of beacon-lazy-signals.min.js as it shipped in the same release. The beacon loads the chunk with that hash as its integrity and with crossorigin="anonymous". A chunk that differs by one byte never runs, and the beacon then behaves as it does when the chunk is blocked: the 22 lazy signals are missing.
Only the script build has the retry, and it only helps for a version already published to npm. To let it run when you load the beacon from a Vouched KYA origin, allow https://cdn.jsdelivr.net in script-src. A host-allowlist policy without it blocks the retry, reports a violation, and leaves the chunk missing, exactly as without the retry. A policy with 'strict-dynamic' ignores the host list for scripts the beacon inserts, so the retry runs whatever the list says.
crossorigin="anonymous" makes the chunk request a CORS request without credentials. A host that serves the chunk from another origin than the page must send Access-Control-Allow-Origin. The Vouched KYA-hosted file and public CDNs such as jsDelivr do. Your script-src rules don't change.
The check covers the lazy chunk only. It doesn't cover beacon.min.js itself, which you pin with an integrity attribute on your own tag (see Script tag), or the worker file, because a Worker constructor has no integrity option.
Trusted Types
A page that enforces Trusted Types (require-trusted-types-for 'script') must allow the beacon's policy by name, next to its own policies:
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types checkpoint-beacon;From 1.4.3 the beacon creates one policy, checkpoint-beacon, once per page. It passes only its own inputs through it: an http: or https: URL naming beacon.worker.js or beacon-lazy-signals.min.js on the page's own origin (in the directory the beacon's script was loaded from, or at a workerUrl or lazySignalsUrl you configured), and the fixed, script-free document a fingerprint probe renders in a hidden iframe. Every copy of the beacon shares that one policy, so the directive needs no 'allow-duplicates'.
Inside a cross-site iframe
Install the script tag in the framed document, not the page that embeds it. The beacon then works as it would on a top-level page of the frame's origin: it loads its worker and lazy chunk from next to the frame's beacon.min.js, and every batch goes out with the frame's Origin. Posture is issued for that origin too, so list the frame's origin, not the embedding page's, as the project's domain or under Additional site origins.
Chromium refuses the beacon's SameSite=Lax cookies in a cross-site frame, and other browsers block or partition third-party cookies. Without them, each load of the frame starts a new session and no posture cookie is written. Read both from onReceipt instead: store browserSessionId and pass it back as the browserSessionId option, and send the latest posture.token to your server in the KYA-Posture header (see Verifying the posture token).
Domains, proxies and CDNs
Detection works on any page that loads the beacon. The domain settings matter only for the signed posture token, the __Host-checkpoint_posture_* cookie that enforcement reads.
Site URL and additional site origins
Ingest issues a posture token only when the page's origin is one the project allows. Verifying the posture token has the matching rule. The rest is here:
- Site URL (the project's primary domain): its
https://origin is always allowed. A bare host such aswww.example.comreads ashttps://www.example.com. A Site URL with a path, withhttp://, or with a username is ignored. With no additional site origins either, posture is withheld asdomain-unset. - Additional site origins: up to 20 more.
Edit them on the project's Installations page, in the Browser posture card.
Add a custom storefront domain,
wwwnext to the apex, staging hosts, or every host your pages load on. The Shopify app adds the store's own domains for you and never removes ones you added.
Rules for each entry:
https://only, with no IP addresses and no username.https://*.example.comcovers every subdomain ofexample.com(shop.example.com,a.b.example.com) but neverexample.comitself. List the apex separately.- A wildcard over a shared hosting suffix is refused, because other tenants of that platform could mint posture for your project:
*.myshopify.com,*.vercel.app,*.netlify.app,*.pages.dev,*.github.io, and similar, plus single labels (*.com) and country second levels (*.co.uk). - The signed token always names the one concrete page origin that matched, never the pattern. The Gateway accepts it only on that origin. A server SDK accepts it when that origin is one you configured for the SDK (Set up browser posture).
- A change reaches the Gateway in about a minute. Token issuance at ingest follows within the window given in Verifying the posture token.
List where your pages load, not where the beacon script or ingest is served from.
Putting a proxy or CDN in front of the hosted script
You can serve the hosted script and the ingest from your own domain, under one path prefix such as /_cp. A proxy host needs no entry in Additional site origins. Load the script from that prefix:
<script src="/_cp/beacon.js" data-project-id="YOUR_PROJECT_ID"></script>The script resolves every other URL against its own directory, so the proxy forwards two prefixes and nothing else:
- A proxy set up for the earlier layout, which forwarded
beacon-lazy-signals.min.jsandbeacon.worker.jsat its root, must also forward thebeacon/*prefix besidebeacon.js, and the ingest under the same prefix. - Never rewrite, minify, or recompress a forwarded script.
beacon.jschecks the lazy chunk and the worker against hashes built into it (Integrity check on the lazy chunk). - Caching may follow the upstream headers:
beacon.jsfor 1 hour, and files under/beacon/<hash>/for a year. Those files are named by their content and never change or disappear, so a page still holding the previousbeacon.jsgets the files it was built with. A release reaches your pages within the hour your proxy may cachebeacon.jsplus the hour the browser may. - With the proxy on your pages' origin, everything is same-origin: allow
connect-src 'self',worker-src 'self', andscript-src 'self'or your nonce with'strict-dynamic', plusbase-uri 'none'with a nonce, because the tag's source is relative. Your page policy never nameskya.vouched.id. - Forward the browser's
Originheader untouched. Posture is issued for that origin, and theRefererorigin is used whenOriginis missing.X-Forwarded-Hostand similar headers are ignored, so a proxy that rewritesOrigin, or drops both it andReferer, getsorigin-mismatch. - On a proxy host other than your pages', let the CORS preflight through:
OPTIONSwithContent-Type,X-Project-ID,X-Content-Encoding, andKYA-Posture-ProofinAccess-Control-Request-Headers, and pass the asset responses'Access-Control-Allow-Originand the ingest responses'Access-Control-Expose-Headersthrough. The beacon readsDatefrom those responses to correct a browser clock that is off, and without it a browser more than a minute off fails every proof. - To also forward the visitor IP and TLS fingerprint your edge saw, see Forward edge evidence. For the npm package, the CLI generates a proxy for you: see Serve the beacon through your own domain.
Example: pages on one host, tags served from another
A site serves its pages on https://www.example.com and https://help.example.com, and serves all of its tags from https://tags.example.net, which proxies to Vouched KYA as in the table above with the prefix /checkpoint.
<script
src="https://tags.example.net/checkpoint/beacon.js"
data-project-id="YOUR_PROJECT_ID"
></script>- Site URL:
https://www.example.com. - Additional site origins:
https://help.example.com.https://*.example.comwould also work and covers future subdomains too. tags.example.netis not listed anywhere. It forwards/checkpoint/beacon.js,/checkpoint/beacon/*, and/checkpoint/api/v1/beacon, and passesOriginthrough. The pages are on another origin, so the worker is fetched from/checkpoint/beacon/<hash>/beacon.worker.jsand started from ablob:URL: the pages allowworker-src blob:andconnect-src https://tags.example.net.
Browser compatibility
The package's stated support is Chrome 90+, Firefox 88+, Safari 14+, and Edge 90+. The browser files (beacon.min.js, beacon.worker.js, beacon-lazy-signals.min.js, and beacon.modern.mjs) are built for exactly that floor, so only syntax those browsers lack is lowered. The npm ESM entry targets ES2020.
CI checks syntax esbuild can lower (nothing needed lowering at Chrome 90, Firefox 88, Safari 14, and Edge 90), plus a denylist of runtime APIs it cannot lower (.at(), Object.hasOwn, structuredClone, AbortSignal.timeout, findLast, toSorted, groupBy, Promise.withResolvers, crypto.randomUUID, Error cause, Array.fromAsync) and regex lookbehind.
The one hard requirement is crypto.getRandomValues, which mints session ids. Everything else degrades:
A hanging or failing IndexedDB costs only the holder-of-key binding, never delivery:
Bundle size
beacon.min.js is budgeted at 34 KB gzipped, and the lazy chunk is budgeted at 11 KB gzipped. The measurement is Node 22.23.1 at gzip level 9. The npm package is marked side-effect free, so bundlers drop the exports you don't import.