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 Checkpoint 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 Checkpoint dashboard
No code required. The Pixel works with any website — WordPress, Shopify, static sites, or custom apps.
Prerequisites
- A Checkpoint 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 Checkpoint Project
- Log into your Checkpoint 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 — 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.
Option A — Custom HTML tag (recommended). 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
Option B — Community Template. The official Checkpoint Pixel template (GTM gallery, publisher: Know-That-Ai; older gallery listings may still show the previous AgentShield name until Google syncs the rename) exposes eight fields (Project ID, API Endpoint, Debug Mode, Session Timeout, Respect Do Not Track, Batch Size, Flush Interval, and Enable Fingerprinting). To install it: Add to Workspace, then Tags → New → Custom → Checkpoint Pixel, enter your Project ID, set Triggering to All Pages, and Save → Submit → Publish.
The published template's release build writes its configuration under key names the Pixel loader
doesn't read, so a template-based tag can fail to initialize, or initialize but ignore the
configured endpoint and fingerprinting settings. Use Option A (Custom HTML) until the template is
updated to match the loader's data-* contract, and verify the POST /api/v1/pixel request fires
before relying on a template tag.
The template also has no field for consent gating, IP anonymization, or URL redaction. With Custom
HTML you can set any data-* attribute directly on the script
tag (session timeout, batch size, fingerprinting, DNT, data-require-consent,
data-anonymize-ip, data-strip-fragment, data-scrub-params, data-drop-query); none of those
are configurable through the template.
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 Checkpoint 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. window.AgentShield / agentshield:* remain as deprecated aliases.
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 (compatible; GPTBot/1.0; +https://openai.com/gptbot) - 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 Checkpoint project
- How to install the Marketing Pixel via GTM (Community Template or Custom HTML), 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: