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.

Keep this ID handy. You'll need it for the next step.

Install the Pixel

Choose your installation method:

Recommended for marketing teams.

Option A — Community Template. Install the official Checkpoint Pixel template from the GTM gallery (publisher: Know-That-Ai; older gallery listings may still show the previous AgentShield name until Google syncs the rename): Add to Workspace, then Tags → New → Custom → Checkpoint Pixel, enter your Project ID, set Triggering to All Pages, and Save → Submit → Publish.

Option B — Custom HTML tag. If community templates are disabled, 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

Both options report into the same project. With Custom HTML you can set any option (session timeout, batch size, fingerprinting, DNT) as a data-* attribute on the script tag; the Community Template exposes the same options as configurable fields (all except data-require-consent).

Adding user identification (matching your internal user IDs in the dashboard)? See the full GTM + Next.js integration guide.

For developers adding the pixel directly to HTML.

Add this script 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 actual Project ID.

For frameworks:

// Next.js (app/layout.tsx)
import Script from 'next/script';

export default function Layout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://kya.vouched.id/pixel.js"
          data-project-id={process.env.NEXT_PUBLIC_CHECKPOINT_PROJECT_ID}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Using a plugin (no code needed):

Install the "Insert Headers and Footers" plugin (or similar)
Go to Settings → Insert Headers and Footers
In the Footer section, paste:

<!-- 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 actual Project ID
Click Save

Using theme editor:

Go to Appearance → Theme File Editor
Select header.php (or add to <head> section)
Add the script in the <head> section
Click Update File

Go to Online Store → Themes
Click Actions → Edit code
Open theme.liquid
Find the closing </body> tag
Add the following just before it:

<!-- 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 actual Project ID
Click Save

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.js and a POST to /api/v1/pixel

If you see a 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_agent detection 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

Symptom	Cause	Fix
No network request	Script not added	Re-check installation steps
No `POST` fired	Do Not Track enabled	The pixel honors DNT; set `data-respect-dnt="false"` if appropriate
Blocked request	Ad blocker	Disable ad blocker or use server-side
CSP error	Content Security Policy	Add `kya.vouched.id` to `script-src`

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:

Goal	Next Cookbook
Need more detection signals	Beacon Integration
Want to block detected agents	Gateway Setup
Need server-side detection	Middleware Detection
Integrate with Google Analytics	GA4 Integration

Detect: Pixel Quick Start