Detect: Pixel Quick Start
Add AI agent detection to any website in 5 minutes with zero code
Goal
Add AI agent detection to your website using the Vouched KYA Marketing Pixel. By the end of this cookbook, you'll have:
- Real-time detection of AI agents (ChatGPT, Claude, Perplexity, etc.)
- Bot traffic visibility (Googlebot, scrapers, crawlers)
- Analytics flowing to your Vouched KYA dashboard
No code required. The Pixel works with any website: WordPress, Shopify, static sites, or custom apps.
Prerequisites
- A Vouched KYA account (sign up free)
- A website you control
- Access to add scripts (directly or via tag manager)
Time Estimate
5 minutes (with Google Tag Manager) or 10 minutes (direct install)
Steps
Create a Vouched KYA Project
- Log into your Vouched KYA dashboard
- Click Create project (in the project switcher)
- Enter a Project Name (e.g., "Marketing Site") and your Site URL
- Click Add Domain
The project is created immediately and shows your install snippets. You can always find them again under Installations in the project dashboard.
Get Your Project ID
After creating your project:
- Open Installations in the project's left-rail navigation
- Copy your Project ID from the top of the page: a name-based slug like
acme-corp(or a UUID for older projects). It's also pre-filled in the install snippets there.
Install the Pixel
Choose your installation method:
Recommended for marketing teams.
Custom HTML tag. Use the loader snippet the dashboard generates:
- Go to Tags → New → Tag Configuration → Custom HTML and paste:
<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>- Replace
YOUR_PROJECT_ID, set Triggering to All Pages, then Save → Submit → Publish
Set any other data-* attribute on the same script tag
(session timeout, batch size, fingerprinting, DNT, data-require-consent, data-anonymize-ip,
data-strip-fragment, data-scrub-params, data-drop-query) with another as.setAttribute(...)
line.
Community template. If your Project ID is the only option you set, the Checkpoint Pixel template (GTM gallery, publisher: Know-That-Ai) also works: Add to Workspace, then Tags → New → Tag Configuration → Custom → Checkpoint Pixel, enter your Project ID, set Triggering to All Pages, and Save → Submit → Publish. It loads pixel.js?project-id=YOUR_PROJECT_ID and runs the Pixel with its defaults. It can't set any other data-* option: if you uncheck its Enable Fingerprinting box or set its API Endpoint to a custom URL, the tag stops without loading the Pixel.
Earlier versions of the template sent ?project_id= and never started the Pixel. If the browser
console shows [Checkpoint] No project ID provided, accept the template update under
Templates in your GTM workspace and Submit → Publish the container, or replace the tag
with the Custom HTML tag above.
Adding user identification (matching your internal user IDs in the dashboard)? See the full GTM + Next.js integration guide.
Verify Installation
- Visit your website in a new browser tab
- Open browser DevTools (F12 or Cmd+Shift+I)
- Go to the Network tab
- Filter by "kya" or "pixel"
- Refresh the page
- You should see a request to
kya.vouched.id/pixel.jsand aPOSTto/api/v1/pixel
200 OK response, the Pixel is working.View Your First Detections
- Return to your Vouched KYA dashboard
- Select your project
- Go to Analytics
- Wait up to 60 seconds for data to appear
You'll see:
- Detection breakdown by class (human, ai_agent, bot)
- Traffic timeline with detection events
- Top agents identified on your site
Track custom events
Once the pixel has loaded, send your own events via window.Checkpoint.track:
<script>
// Guard on the global: calls before pixel.js loads are lost (there is no queue)
window.Checkpoint && window.Checkpoint.track('signup', { plan: 'pro' });
</script>See the Pixel reference for the full window.Checkpoint API (identify, reset, grantConsent, getSession) and the checkpoint:* events.
Verify It's Working
Quick Check
Open your browser console and run:
// Check if the pixel loaded
window.Checkpoint && window.Checkpoint.initialized ? 'Pixel loaded!' : 'Pixel not found';Test with a spoofed User-Agent
The pixel runs in the browser, so a plain curl request won't trigger it: curl doesn't execute JavaScript, so pixel.js never runs. To test agent detection, override your browser's User-Agent and reload:
- Open DevTools → Network conditions
- Uncheck "Use browser default" and set a custom UA, e.g.
Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot - Reload the page
- Check your dashboard: you should see an
ai_agentdetection within seconds
To test detection with curl (a non-browser client), use the server-side
Middleware or Gateway instead: those inspect the request
directly and don't rely on client-side JavaScript.
Troubleshooting
Pixel Not Loading
No Detections in Dashboard
- Wait 60 seconds: Data takes a moment to appear
- Check Project ID: Must match your dashboard project
- Verify GTM published: Unpublished changes won't work
- Check Do Not Track: With DNT on, the pixel collects nothing by default
Content Security Policy (CSP)
If your site uses CSP, add this to your script-src directive:
Content-Security-Policy: script-src 'self' https://kya.vouched.id;What You Learned
- How to create a Vouched KYA project
- How to install the Marketing Pixel via a GTM Custom HTML tag, direct install, WordPress, or Shopify
- How to send custom events with
window.Checkpoint.track - How to verify the Pixel is working and view detection data in the dashboard
Next Steps
Now that you have detection running, consider: