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

  1. The Pixel script loads asynchronously after your page renders
  2. It collects detection signals (user agent, headers, behavior, and, when enabled, a browser fingerprint)
  3. Signals are POSTed to the Vouched KYA detection API (POST /api/v1/pixel)
  4. The result (classification + confidence) is logged to your project
  5. 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:

AttributeDefaultDescription
data-project-idRequiredYour Vouched KYA Project ID
data-debugfalse"true" enables verbose console logging
data-api-endpoint<origin>/api/v1/pixelOverride the ingestion endpoint
data-session-timeoutunsetExplicit idle-gap override in ms, up to six hours. Unset, the gap is 1 hour on phones, 6 hours elsewhere
data-respect-dnttrueHonor the browser Do Not Track signal ("false" to disable)
data-batch-size10Events per batch
data-flush-interval5000Batch send interval (ms)
data-enable-fingerprintingtrueCollect a browser fingerprint ("false" to disable)
data-require-consentfalseHolds the device id and identity cookie until grantConsent() is called
data-anonymize-iptrueTruncates the IP (IPv4 /24, IPv6 /48) before storage ("false" keeps the full address)
data-strip-fragmenttrueStrip the #fragment from url/referrer ("false" to disable)
data-scrub-paramsnoneComma-separated query param names to redact even when allowlisted (utm_*) in url/referrer
data-drop-queryfalse"true" drops the whole query string from url/referrer

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:

Method / propertyDescription
track(eventName, data?)Send a custom event
identify(userId, traits?)Associate a user id (traits are sent server-side only, never stored in the cookie; rate-limited)
getUser()Returns { id } for the identified user, or null
grantConsent()Lifts data-require-consent: stores and sends the device id, with one identify event if the pageview left first
reset()Clear identity + cookie and start a fresh anonymous session (logout / GDPR)
handoffUrl(url)Resolves with url plus a single-use checkpoint_handoff token that carries this session to another device or domain (see Sessions)
getSession()Returns { id, startTime, duration, userId }
getInitInfo()Returns version/init diagnostics (useful for duplicate-load debugging)
lastDetectionThe most recent agent detection object. Unset until an agent is detected: human traffic never populates it

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 user
  • traits (object, optional): Additional user properties

Important Notes:

  • User ID is stored in cookies for persistent identification (not until grantConsent() when data-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 from identify(), 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 identified

Note: 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() when data-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 event
  • data (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:

Eventdetail
checkpoint:detectionthe detection result (isAgent, confidence, …). Fires only when an agent is detected, not on every pageview
checkpoint:identify{ userId, traits, sessionId, deviceId }. deviceId is absent for a Do Not Track visitor
checkpoint:reset{ previousUserId, newSessionId }
checkpoint:loaded{ version, projectId }. Fires once, as soon as the script is present, before any collection

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.

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_session cookie, the session record and the stored nonce, and drops a user restored from a cookie. An identify() 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_handoff parameter that arrived with the page is redeemed on the first event after that.
  • checkpoint:loaded still 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 first identify() 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, handoffUrl resolves 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.
  • handoffUrl resolves 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), handoffUrl resolves 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.status is unavailable), 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_handoff parameter is removed from the url and referrer the 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

FeaturePixelBeacon
InstallationScript tag / GTMnpm package or script tag
Code requiredNoneYes
Signal richnessBasic + fingerprintAdvanced
Event trackingtrack()trackEvent()
Web WorkerNoOptional (useWorker)
Bundle size≈8 KB gzipped, plus ≈3 KB for the fingerprint detector it loads when data-enable-fingerprinting is on (the default)Under 37 KB gzipped (script tag: 35 KB bundle + 2 KB loader)
Best forMarketing, analyticsApplication integration

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.js and a POST /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 the checkpoint_user and agentshield_user cookies, the _as_beacon_session cookie 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