Overview

The Checkpoint Marketing Pixel is a no-code solution for detecting AI agents and bots on your website. It integrates with Google Tag Manager (GTM) and other tag management systems, requiring no developer involvement.

For a technical overview of the Pixel's detection capabilities and how it compares to other detection methods, see Detection Methods.

Why Use the Marketing Pixel?

For Marketing Teams

No coding required — Install through GTM interface
Quick deployment — Live in minutes
Easy configuration — Visual interface for settings
A/B testing ready — Test different responses

Analytics Integration

Google Analytics 4 — Automatic event tracking
Custom dimensions — Rich agent detection data
Audience building — Segment real users from bots
Conversion tracking — Accurate conversion metrics

Bot Protection

Ad fraud prevention — Block fake ad clicks
Form spam protection — Stop automated submissions
Content scraping — Protect your content
Inventory protection — Hide pricing from competitors

Installation Methods

GTM Installation

Step 1: Import the Template

Log into Google Tag Manager
Navigate to Templates → Tag Templates
Click Search Gallery
Search for "Checkpoint" (or "AgentShield")
Click Add to Workspace
Click Add to confirm

If the template isn't in the gallery yet, you can import it manually from our GitHub repository. Download the template.tpl file and import it using GTM's template import feature.

Manual Template Import (Alternative)

If you can't find the template in the gallery:

Visit our GitHub repository
Download the template.tpl file
In GTM, go to Templates → Tag Templates → New
Click the ⋮ menu → Import
Select the downloaded template.tpl file
Click Save

Step 2: Create the Tag

Go to Tags → New
Click Tag Configuration
Select Checkpoint Pixel from Custom templates
Configure:
- Project ID: Enter your Project ID from the dashboard
- Debug Mode: Enable for testing

Step 3: Set Triggers

Click Triggering
For Single Page Applications (SPAs):
- Create a History Change trigger (for React, Vue, Angular)
- Go to Triggers → New → Trigger Configuration
- Select History Change as trigger type
- Name it "All History Changes"
- Apply this trigger to your Checkpoint tag
For Traditional websites:
- Select All Pages trigger
Optional: Add custom triggers for specific events

SPA Tracking Note: The Checkpoint pixel automatically detects and tracks SPA navigation events including:

History API changes (pushState/replaceState)
Browser back/forward navigation (popstate)
Hash changes (hashchange)

However, configuring GTM's History Change trigger ensures redundancy and allows you to track additional GTM variables with each navigation.

Step 4: Test & Publish

Click Preview to test in debug mode
Verify the pixel fires correctly
Check detection events in preview
Click Submit to publish
Add version notes and Publish

Direct JavaScript Installation

Add this code to your website's <head> or before the closing </body> tag:

<!-- Checkpoint Pixel -->
<script
  src="https://kya.vouched.id/pixel.js"
  data-project-id="YOUR_PROJECT_ID"
  data-debug="false">
</script>

Replace YOUR_PROJECT_ID with your actual Project ID from the Checkpoint dashboard.

What the pixel does automatically:

Automatic detection — Identifies AI agents and bots on every pageview
SPA tracking — Detects navigation in React, Vue, Angular apps
Session persistence — Maintains session across page reloads
User identification — Ready for window.AgentShield.identify() calls
Debug mode — Set data-debug="true" to see detailed console logs

Configuration Options

The pixel script accepts configuration via data attributes or query parameters:

Method 1: Data Attribute (Recommended)

<script
  src="https://kya.vouched.id/pixel.js"
  data-project-id="YOUR_PROJECT_ID">
</script>

Method 2: Query Parameter (For Shopify ScriptTag API)

<script src="https://kya.vouched.id/pixel.js?project-id=YOUR_PROJECT_ID"></script>

Attribute	Description	Default
`data-project-id`	Your Checkpoint Project ID (preferred method)	—
Query param `?project-id=`	Alternative: Project ID as URL query parameter	—
`data-debug`	Enable debug console logging	`false`
`data-session-timeout`	Session timeout in milliseconds	`1800000` (30 min)
`data-respect-dnt`	Honor Do Not Track browser setting	`true`
`data-enable-fingerprinting`	Enable browser fingerprinting	`true`

Verifying Installation

Open your browser's Developer Tools console:

// Check if the pixel is loaded
console.log('Pixel loaded:', typeof window.AgentShield !== 'undefined');

// Get initialization info
console.log(window.AgentShield?.getInitInfo());

// Expected output:
// {
//   version: "1.1.0",
//   initialized: true,
//   sessionId: "abc-123...",
//   projectId: "YOUR_PROJECT_ID"
// }

If you see initialized: true, the pixel is working correctly.

Next.js Installation

Content Security Policy (CSP) Configuration

If you have CSP headers configured, you must allowlist the Checkpoint domain or the pixel will be blocked.

Required CSP Directives:

script-src: Must include https://kya.vouched.id
connect-src: Must include https://kya.vouched.id

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: [
              "default-src 'self'",
              "script-src 'self' 'unsafe-inline' https://kya.vouched.id",
              "connect-src 'self' https://kya.vouched.id",
              // ... your other CSP directives
            ].join('; ')
          }
        ]
      }
    ]
  }
}

Only add https://kya.vouched.id to your existing CSP directives. Don't replace your entire CSP policy with this example.

Adding the Pixel

Use Next.js's <Script> component with strategy="afterInteractive":

App Router (app/layout.tsx)

import Script from 'next/script';

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

Pages Router (_app.tsx)

import Script from 'next/script';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Script
        src="https://kya.vouched.id/pixel.js"
        data-project-id={process.env.NEXT_PUBLIC_CHECKPOINT_PROJECT_ID}
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}

For server-side detection in Next.js, use the Middleware instead. The Pixel is client-side only.

Adobe Launch Installation

Step 1: Create Data Element

Go to Data Elements → Add Data Element
Name: "Checkpoint Project ID"
Extension: Core
Data Element Type: Custom Code
Code:
```
return 'YOUR_PROJECT_ID';
```

Step 2: Create Rule

Go to Rules → Add Rule
Name: "Checkpoint Detection"
Events: Add "Page Bottom" or "DOM Ready"
Actions: Add Action
- Extension: Core
- Action Type: Custom Code

Step 3: Add Pixel Code

var script = document.createElement('script');
script.src = 'https://kya.vouched.id/pixel.js';
script.setAttribute('data-project-id', _satellite.getVar('Checkpoint Project ID'));
document.head.appendChild(script);

Step 4: Publish

Save the rule
Build for Development
Test in staging
Build for Production

Google Analytics 4 Integration

Automatic Event Tracking

The pixel automatically sends events to GA4 when configured:

// Events sent to GA4
gtag('event', 'checkpoint_detection', {
  detection_class: 'ai_agent',
  confidence: 85,
  agent_name: 'ChatGPT',
});

Custom Dimensions Setup

In GA4, go to Configure → Custom Definitions
Create custom dimensions:
- detection_class (Text)
- confidence (Number)
- agent_name (Text)

Audience Creation

Go to Configure → Audiences
Create "Real Users" audience:
- Condition: detection_class = human
Create "Detected Agents" audience:
- Condition: detection_class = ai_agent

JavaScript API Reference

The pixel exposes a window.AgentShield object with methods for user identification and session management.

Available Methods

// Identify a user (for user tracking)
window.AgentShield.identify(userId, traits);

// Reset user identification (on logout)
window.AgentShield.reset();

// Get current identified user
window.AgentShield.getUser();

// Get session information
window.AgentShield.getSession();

// Track custom events
window.AgentShield.track(eventName, data);

// Get initialization status (debugging)
window.AgentShield.getInitInfo();

// Grant consent for cookies (GDPR)
window.AgentShield.grantConsent();

identify(userId, traits)

Associates a user with the current session. Call this when users log in.

window.AgentShield.identify('user_123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
});

reset()

Clears user identification. Call this when users log out.

window.AgentShield.reset();

track(eventName, data)

Track custom events.

window.AgentShield.track('button_click', {
  button: 'signup',
  page: '/pricing',
});

For complete user identification documentation, see the User Identification guide.

Common Use Cases

Form Spam Prevention

document.getElementById('form').addEventListener('submit', function (e) {
  const initInfo = window.AgentShield?.getInitInfo();
  if (initInfo?.detectionClass === 'ai_agent') {
    e.preventDefault();
    alert('Please verify you are human');
  }
});

Ad Fraud Prevention

// Only load ads for real users
if (window.AgentShield?.getInitInfo()?.detectionClass === 'human') {
  loadAdsense();
  loadDisplayAds();
}

Privacy & Compliance

Always comply with privacy regulations in your jurisdiction. The pixel respects user privacy preferences by default.

The pixel respects data-respect-dnt="true" (default) and provides a consent API:

// Grant consent for cookies
window.AgentShield.grantConsent();

Troubleshooting

Pixel Not Loading

Check that the Project ID is correct
Verify the script tag is in your HTML
Check for Content Security Policy blocks in the browser console
Ensure no ad blockers are interfering

No Detections in Dashboard

Enable debug mode (data-debug="true")
Check browser console for initialization messages
Verify the Project ID matches your dashboard project
Check that GTM is published (if using GTM)

Next Steps

Detection Methods — Compare Pixel vs Beacon vs Middleware
JavaScript Beacon — Advanced client-side detection with WebWorker support
Technical Pixel Guide — Technical implementation details
Dashboard Analytics — View your detection data
User Identification — Track authenticated users
Enforce — Add enforcement to your detection

Marketing Pixel

On this page