Marketing Pixel
Lightweight, no-code AI agent detection for analytics and marketing teams
Overview
The Vouched KYA Marketing Pixel is a lightweight, no-code detection snippet that identifies AI agents and bots visiting your website. It loads asynchronously, has minimal impact on page performance, and installs via a simple script tag or your tag manager.
The Pixel is ideal for:
- Marketing teams who want bot traffic visibility without developer involvement
- Analytics teams who need to separate real users from automated traffic
- Content teams who want to monitor AI scraping activity
The pixel registers its JavaScript API on window.Checkpoint and stores its device id in the
checkpoint_user cookie, for anonymous visitors as well as identified ones, so a returning
browser keeps the same device id across page loads. The
beacon (1.4.3 and later) reads and
writes the same cookie for its deviceId, so both surfaces report one id for a browser.
Behavior change: a persistent device cookie for anonymous visitors. Earlier pixel versions
wrote the checkpoint_user cookie only when your page called identify(). The pixel now writes
it on a visitor's first page view and renews it on every load, with a 365 day lifetime, so a
returning browser keeps one device id. Update your cookie disclosure to list it. The pixel does
not write the cookie for a visitor who sends Do Not Track (honored by default, see
data-respect-dnt), and on a Shopify storefront it waits until the Shopify Customer Privacy API
reports that the visitor has granted consent. A visitor without the cookie sends no device id and
is counted per page view, as before.
Prerequisites
You'll need your Project ID before installing the Pixel: see Credentials for where to find it under Installations in your project dashboard.
Installation
Add the following script tag in your HTML <head> section:
<!-- Detect Pixel -->
<script>
(function () {
var as = document.createElement('script');
as.type = 'text/javascript';
as.async = true;
as.src = 'https://kya.vouched.id/pixel.js';
as.setAttribute('data-project-id', 'YOUR_PROJECT_ID');
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(as, s);
})();
</script>
<!-- End Detect Pixel -->Replace YOUR_PROJECT_ID with your Project ID (see Credentials). This is the exact snippet the dashboard generates for you.
How It Works
- The Pixel script loads asynchronously after your page renders
- It collects detection signals (user agent, headers, behavior, and, when enabled, a browser fingerprint)
- Signals are POSTed to the Vouched KYA detection API (
POST /api/v1/pixel) - The result (classification + confidence) is logged to your project
- View results in the dashboard
The Pixel never blocks page rendering and adds no perceptible latency to the user experience.
Configuration
Project ID
Every Pixel installation requires a Project ID, set via data-project-id. See
Credentials for where to find it.
Script attributes
All options are set as data-* attributes on the script tag:
To send events through your own CDN instead of straight to Vouched KYA, point data-api-endpoint at a path your edge proxies. See Forward edge evidence.
data-anonymize-ip defaults to true for both the pixel and the Beacon.
Vendor IP verification (matching a request's IP against an AI vendor's published ranges) needs the
full address, so set data-anonymize-ip="false" if you need vendor IP attribution and accept
storing the full IP.
What data leaves the page. Every pageview sends the current page's url, document.referrer,
and document.title, plus the standard browser/device signals (user agent, screen size,
timezone, and, when enabled, a fingerprint). Redaction runs client-side, before any of it is
collected. url and referrer keep the scheme, host and path; a path segment that looks like an
email address, a phone number or a secret token, or is longer than 256 characters, becomes
[redacted]; every query parameter name is kept, and every query value becomes [redacted]
except utm_source, utm_medium, utm_campaign, utm_term and utm_content (also redacted
when they look like an email address, a phone number or a token, or are longer than 256
characters). Credentials embedded in the URL are dropped. data-strip-fragment
(on by default) strips the #fragment: never sent to the server by any other web surface, and the
highest-risk part of a URL for tokens (SPA routers, magic links, OAuth implicit flow).
data-scrub-params also redacts the utm_* names you list, and data-drop-query removes the
query string entirely. title has no redaction option: avoid putting sensitive values in
<title> if that's a concern.
Subresource Integrity (SRI)
Every pixel build also publishes a content-addressed, versioned path
(/pixel/<version>.js) alongside the default /pixel.js. Pin the version
and its integrity hash if you want the browser itself to refuse a
tampered file, rather than trusting whatever the CDN currently serves at
/pixel.js:
<script
src="https://kya.vouched.id/pixel/VERSION.js"
integrity="sha384-INTEGRITY_HASH"
crossorigin="anonymous"
data-project-id="YOUR_PROJECT_ID"
></script>Find the current VERSION and INTEGRITY_HASH in your dashboard's
installation snippet, or by fetching /pixel-integrity.json. A versioned
URL is immutable: a new pixel build always publishes a new version rather
than overwriting an old one, so pinning one never silently changes under
you; upgrade by re-copying the snippet.
Custom Events
Send custom events with the window.Checkpoint.track method:
<script>
// Guard on the global: calls before pixel.js loads are lost (there is no queue)
window.Checkpoint &&
window.Checkpoint.track('form_submit', {
form_id: 'contact',
page: '/contact',
});
</script>JavaScript API
Once pixel.js loads, it exposes window.Checkpoint:
window.Checkpoint.identify(userId, traits)
Identifies a user and associates them with the current session. Common uses:
- Unified Analytics: Sync user data between Vouched KYA, Google Analytics, Amplitude, and other analytics platforms
- Personalized AI Responses: Track authenticated users' AI agent interactions
- Session Attribution: Connect unattributed AI sessions to known users when they log in
- Cross-Platform Tracking: Maintain user identity across different AI platforms and sessions
Important: This feature is for your customer-facing website, not the Vouched KYA dashboard. The userId comes from your existing analytics (Amplitude, GA4, etc.), not from Vouched KYA.
Parameters:
userId(string, required): Unique identifier for the usertraits(object, optional): Additional user properties
Important Notes:
- User ID is stored in cookies for persistent identification (not until
grantConsent()whendata-require-consent="true", on a Shopify storefront only after the buyer allows analytics; a Do Not Track visitor gets no cookie, session record or nonce fromidentify(), and no event is sent) - User traits (email, name, etc.) are sent to the server and NOT stored in cookies
- Call this method when users log in or when you want to identify a session
identify() enforces a 1-second minimum interval between calls. A call inside that window is
dropped (it returns without sending) and each successive violation doubles an internal backoff, up
to 10 seconds; the counter decays as soon as an allowed call goes through. Rate limiting is skipped
when data-debug="true" or on localhost, so a development run won't reproduce it.
Example:
window.Checkpoint.identify('user_123', {
email: 'john@example.com',
name: 'John Doe',
plan: 'premium',
company: 'Acme Corp',
});Privacy Note: User traits are sent to Vouched KYA servers and stored in your database. Never send sensitive information like passwords or credit card numbers.
window.Checkpoint.getUser()
Returns the currently identified user or null if no user is identified.
Returns:
{
id: 'user_123';
}
// or null if not identifiedNote: User traits are not returned by this method (they're stored server-side only).
Example:
const user = window.Checkpoint.getUser();
if (user) {
console.log('Current user:', user.id);
} else {
console.log('No user identified');
}window.Checkpoint.reset()
Clears the current user identification and starts a new anonymous session. Call this when users log out.
What it does:
- Clears user ID from cookies
- Generates new session ID
- Generates new device ID and stores it in the cookie (not stored until
grantConsent()whendata-require-consent="true", not for a Do Not Track visitor, and on a Shopify storefront only after the buyer allows analytics) - Sends logout event to server
Example:
// On user logout
window.Checkpoint.reset();
console.log('User identification cleared');window.Checkpoint.track(eventName, data)
Track custom events for analytics and detection.
Parameters:
eventName(string, required): Name of the eventdata(object, optional): Additional event data
Example:
// Track form submission
window.Checkpoint.track('form_submit', {
form_id: 'contact-form',
page: window.location.pathname,
});
// Track button click
window.Checkpoint.track('button_click', {
button: 'pricing-cta',
plan: 'enterprise',
});Events
The pixel also dispatches window CustomEvents you can listen for:
What about bots and humans?
checkpoint:detection and lastDetection are gated on isAgent, which is true only for interactive AI assistants: ChatGPT, Claude, Perplexity. Bots (Googlebot, GPTBot, headless browsers) and humans classify with isAgent: false, so neither fires the event nor populates lastDetection. If you wire a GA4 forward off checkpoint:detection (as shown below), you are measuring AI-assistant traffic only, not all automation.
Every classification (agent, bot, and human alike) is still sent server-side and appears in the dashboard. Client-side, the pixel also records the last result to sessionStorage regardless of class:
// Written on every detection, not just agents.
const recent = JSON.parse(sessionStorage.getItem('checkpoint_recent_detection') || 'null');
// → { isAgent: boolean, isBot: boolean, confidence: number, timestamp: number }Read isBot there to react to crawler traffic on the client.
checkpoint:identify fires when a user is identified, which is useful for syncing with other
analytics tools; checkpoint:reset fires when identification is reset (logout):
window.addEventListener('checkpoint:identify', (event) => {
console.log('User identified:', event.detail);
// event.detail contains: { userId, traits, sessionId, deviceId }
});
window.addEventListener('checkpoint:reset', (event) => {
console.log('User reset:', event.detail);
// event.detail contains: { previousUserId, newSessionId }
});For an end-to-end walkthrough of wiring identify() into your login flow, with framework patterns
for Next.js and React plus verification and troubleshooting, see the Identify Users
cookbook. To identify users via Google Tag Manager, see
the GTM + Next.js guide.
The pixel honors Do Not Track by default (data-respect-dnt) and auto-tracks SPA navigations
(History pushState/popstate/hashchange). It stores a device id in the checkpoint_user
cookie on the first page load, without a call to identify() (deferred until grantConsent()
when data-require-consent="true", not written at load for a Do Not Track visitor, and on a
Shopify storefront only after the buyer allows analytics). Events carry the device id only once it
is stored in that cookie, so a visitor whose cookie cannot be written sends none. When two copies
of the checkpoint_user or agentshield_user cookie hold different values, the pixel sends no
device id, restores no user id, and writes neither cookie, the same rule the beacon follows. For a
Do Not Track visitor the pixel also clears what it already holds at load: the checkpoint_user
and agentshield_user cookies, the _as_beacon_session cookie and this project's stored nonces.
Shopify buyer consent
On a Shopify storefront the pixel gates itself on Shopify's
Customer Privacy API. The gate engages whenever
window.Shopify is present with a storefront signal (Shopify.shop, loadFeatures, or
customerPrivacy); pages without window.Shopify behave exactly as described above.
While the gate is engaged:
- Consent counts as not granted until Shopify reports analytics processing allowed, either because the buyer accepted or because consent is not required in their region.
- No identity or session cookie is written, no device id is sent and every outbound event is
dropped. The fingerprint detector is not loaded either. Calls to
track()before consent are discarded, not queued.identify()keeps the user id in memory and applies it when analytics is allowed. - The pixel reads the current answer on load and listens for
visitorConsentCollected, so a buyer who accepts the banner later starts being collected in the same page view. A later withdrawal, or any answer that does not allow analytics (including at load and when the consent API fails to load), stops further sends and expires the pixel's identity cookies (checkpoint_user,agentshield_user), the_as_beacon_sessioncookie, the session record and the stored nonce, and drops a user restored from a cookie. Anidentify()made in this page view and the in-memory device id are kept and applied on a later grant. When analytics had been allowed and is then withdrawn, the in-memory identity is forgotten too, so a later grant starts a new session and a fresh device id, unless another surface has already written the session cookie or the identity cookies, which are adopted. - When consent is granted the pixel lifts the hold itself: the session cookie is adopted from
another surface or written under the id the page already holds, and a
checkpoint_handoffparameter that arrived with the page is redeemed on the first event after that. checkpoint:loadedstill fires regardless of consent. It means only that the script is present.- If Shopify's consent API fails to load, the gate fails closed and nothing is sent.
grantConsent() does not lift this hold, so a host cannot override it; Shopify's answer alone
decides. The theme app extension handles
installation; see the Shopify app for setup.
Sessions
The pixel keys every event to a visitor session stored in the first-party _as_beacon_session cookie, the same cookie the beacon reads and writes. The value is a random UUID. A second cookie, _as_beacon_session_meta, holds two short hashes (the campaign parameters and the user the session started under) so both surfaces can tell when a session should end. Both cookies are host-only (path=/, SameSite=Lax, no Domain) and are written only when cookies are allowed: never for a Do Not Track visitor, and never on a Shopify storefront before the buyer allows analytics.
A new session starts when:
- There is no session cookie (a first visit, or the cookie expired).
identify()is called with a user id different from the one the session already has. The firstidentify()after anonymous browsing keeps the session.reset()is called.- A Shopify buyer withdraws analytics consent. The pixel expires the cookies and starts a new in-memory session; when the buyer allows analytics again the cookie is adopted or written under that id.
- A page loads with campaign parameters (
utm_source,utm_medium,utm_campaign,utm_term,utm_content,gclid,fbclid,msclkid) that differ from the ones stored with the current session. A load without campaign parameters never splits a session.
The referrer never splits a session, so returns from an OAuth or payment provider keep the session they left.
Because no browser event marks the end of a visit, a session also ends after an idle gap: 1 hour on phones and 6 hours elsewhere, chosen by the userAgentData.mobile flag when the browser sends it and by the user agent otherwise. This is the one timer. It is the cookie's sliding expiry, rewritten on every event, and data-session-timeout overrides it, up to six hours.
Carrying a session to another device or domain
window.Checkpoint.handoffUrl(url) asks Vouched KYA for a token bound to your project and the current session and resolves with url plus a checkpoint_handoff parameter. Put that URL in an email, a QR code, or a link to another domain that runs the same project's pixel or beacon. The landing page sends the token with its first event, and Vouched KYA continues the original session there. The page then strips the parameter from the address bar.
const link = await window.Checkpoint.handoffUrl('https://shop.example.com/cart');- The token is an opaque random value that Vouched KYA stores for 15 minutes. The URL carries no session id.
- Vouched KYA only issues a token for a session it has seen: the request must carry the nonce from the session's latest response, which stays valid for 10 minutes. After longer idle,
handoffUrlresolves the URL unchanged until the next event refreshes the nonce. - It works once. The first page to redeem it continues the session. 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; neither does a pixel hit before consent when the install requires consent or the Shopify Customer Privacy API has not granted it, because the pixel sends no device id until then.
- The reach of a leaked link is bounded by counts: 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. Beyond that the landing page starts a fresh session. If the visitor on the destination page is identified as a different user than the one who made the link, the redemption is rejected, the landing page keeps its own session and the token stays unspent. An anonymous destination records the issuing user on the adopted session.
- A redemption clears any automation verdict armed on the original session, so the landing device does not inherit it.
handoffUrlresolves with the URL unchanged, without a network call, when cookies are not allowed and when there is no nonce yet. When the pixel inherited its session from a beacon, that session id is bound to the beacon's browser key, so the pixel signs the request with the key the beacon stored in this origin's IndexedDB. If that key is not reachable (the beacon ran on another subdomain or origin, or the browser cannot sign within 400 ms),handoffUrlresolves with the URL unchanged, without a network call. It also resolves with the URL unchanged, after the request, when Vouched KYA cannot issue a token.- The token is redeemed only on an event that carries a device id, because Vouched KYA rejects a redemption without one. A pixel held by the Shopify Customer Privacy API keeps the token, without sending it or removing the parameter, until the buyer allows analytics, and drops it and removes the parameter when the buyer denies or withdraws. With Do Not Track on, the pixel removes the parameter from the address bar and never redeems it. If Vouched KYA could not reach its handoff state in time (
handoff.statusisunavailable), the parameter stays and the next event retries, up to three attempts; after the third the pixel drops the token and removes the parameter. - The response is applied only if the session did not change in the meantime: a
reset(),identify()or consent change during the round trip wins. - The
checkpoint_handoffparameter is removed from theurlandreferrerthe pixel sends.
Analytics Integration
Google Analytics 4
The pixel does not push to GA4 or the dataLayer on its own. Instead, listen for the checkpoint:detection event and forward it to GA4 yourself:
<script>
window.addEventListener('checkpoint:detection', function (e) {
var d = e.detail || {};
// Forward to GA4 (gtag must already be installed)
window.gtag &&
window.gtag('event', 'checkpoint_detection', {
is_agent: d.isAgent,
confidence: d.confidence,
});
});
</script>This lets you build GA4 audiences that exclude bot traffic and measure true conversion rates.
Pixel vs Beacon
For more advanced client-side collection, see the Beacon.
Troubleshooting
Pixel Not Loading
- Check that the Project ID is correct
- Verify no ad blockers or content security policies are blocking the script
- Check the browser console for errors (set
data-debug="true")
No Detections in Dashboard
- Confirm the Pixel is loading (check the Network tab for
pixel.jsand aPOST /api/v1/pixel) - Verify the Project ID matches your dashboard project
- Check that GTM is published (if using GTM)
- If the visitor's browser sends Do Not Track, the pixel collects nothing and writes no identity, session or nonce state unless you set
data-respect-dnt="false". At load it also expires thecheckpoint_userandagentshield_usercookies, the_as_beacon_sessioncookie and the stored nonces the visitor already holds - On a Shopify store, nothing is sent until the buyer's consent is granted or Shopify reports that consent is not required in their region (see Shopify buyer consent)
Content Security Policy
The Pixel loads pixel.js and checkpoint-detector.js from kya.vouched.id and sends events there with fetch, so a CSP needs the host in both directives:
Content-Security-Policy: script-src 'self' https://kya.vouched.id; connect-src 'self' https://kya.vouched.id;If you set data-api-endpoint, allow that host in connect-src instead.
Next Steps
- Pixel Cookbook: Step-by-step pixel setup guide
- Identify Users Cookbook: Associate pixel sessions with your authenticated users
- Beacon: Advanced client-side detection
- Dashboard Analytics: View your detection data
- Enforce: Add enforcement to your detection