Overview

The Checkpoint JavaScript Beacon is a full-featured client-side SDK for AI agent detection. It provides real-time detection, event tracking, WebWorker offloading, and intelligent batching — all with under 5ms page load impact.

Key Features

< 5ms page load impact — Non-blocking execution
~41KB gzipped — Lightweight bundle
WebWorker support — Offload detection from the main thread
Automatic batching — Efficient network usage with smart queue management
Compression — Reduces bandwidth consumption
TypeScript — Full type definitions included
Offline resilience — Queues events when offline, sends when reconnected

Installation

npm install @kya-os/agentshield-beacon

yarn add @kya-os/agentshield-beacon

pnpm add @kya-os/agentshield-beacon

Quick Start

import { AgentShieldBeacon } from '@kya-os/agentshield-beacon';

const beacon = new AgentShieldBeacon({
  projectId: 'YOUR_PROJECT_ID',
  endpoint: 'https://kya.vouched.id/api/v1',
});

// Start detection
await beacon.start();

How It Works

The Beacon automatically selects the best execution mode:

WebWorker Mode (preferred) — Separate thread, zero UI impact
Fallback Mode — Uses requestIdleCallback on older browsers
Direct Mode — Synchronous for critical events

Browser capabilities are detected automatically.

Configuration

const beacon = new AgentShieldBeacon({
  // Required
  projectId: 'YOUR_PROJECT_ID',

  // Endpoint configuration
  endpoint: 'https://kya.vouched.id/api/v1',

  // Detection settings
  autoStart: true, // Start detection on initialization
  debug: false, // Enable debug logging

  // Batching
  batchSize: 10, // Events per batch
  batchInterval: 5000, // Send interval in ms
  maxQueueSize: 100, // Maximum queued events

  // Transport
  compression: true, // Compress payloads
  retryAttempts: 3, // Retry failed requests
  timeout: 10000, // Request timeout in ms

  // Worker
  useWorker: true, // Enable WebWorker mode
});

Configuration Options

Option	Type	Default	Description
`projectId`	`string`	Required	Your Checkpoint project ID
`endpoint`	`string`	Production URL	API endpoint
`autoStart`	`boolean`	`true`	Start detection immediately
`debug`	`boolean`	`false`	Enable console debug logging
`batchSize`	`number`	`10`	Events per batch
`batchInterval`	`number`	`5000`	Batch send interval (ms)
`maxQueueSize`	`number`	`100`	Max events in queue
`compression`	`boolean`	`true`	Compress request payloads
`retryAttempts`	`number`	`3`	Retry count for failed requests
`timeout`	`number`	`10000`	Request timeout (ms)
`useWorker`	`boolean`	`true`	Use WebWorker when available

API Reference

Core Methods

`start()`

Initialize the beacon and begin detection.

await beacon.start();

`stop()`

Stop detection and flush pending events.

await beacon.stop();

`destroy()`

Completely shut down the beacon and release resources.

beacon.destroy();

Event Tracking

`track(event)`

Send a custom event with detection data:

beacon.track({
  type: 'page_view',
  metadata: {
    page: '/products',
    referrer: document.referrer,
  },
});

`identify(userId)`

Associate a user identity with the beacon session:

beacon.identify('user-123');

Detection Results

`getDetectionResult()`

Get the most recent detection result:

const result = beacon.getDetectionResult();

if (result) {
  console.log(result.detectionClass); // 'human', 'ai_agent', 'bot'
  console.log(result.confidence); // 0-100
  console.log(result.agentName); // e.g., 'ChatGPT'
}

Events

The Beacon emits events you can listen to:

// Detection completed
beacon.on('detection', (result) => {
  console.log(`Detected: ${result.detectionClass} (${result.confidence}%)`);
});

// Batch sent
beacon.on('batch:sent', (batch) => {
  console.log(`Sent ${batch.events.length} events`);
});

// Error occurred
beacon.on('error', (error) => {
  console.error('Beacon error:', error.message);
});

// Connection state changed
beacon.on('online', () => console.log('Back online'));
beacon.on('offline', () => console.log('Gone offline'));

Event Types

Event	Payload	Description
`detection`	`DetectionResult`	Detection classification received
`batch:sent`	`Batch`	Batch of events sent successfully
`batch:error`	`Error`	Batch send failed
`error`	`Error`	General error
`online`	—	Browser went online
`offline`	—	Browser went offline

WebWorker Mode

When useWorker: true (default), the Beacon offloads detection processing to a WebWorker:

Main thread stays free for UI rendering
Detection signals are collected on the main thread and sent to the worker
The worker handles batching, compression, and network requests
Results are posted back to the main thread

import { AgentShieldBeacon } from '@kya-os/agentshield-beacon';
import { BeaconWorkerClient } from '@kya-os/agentshield-beacon';

const beacon = new AgentShieldBeacon({
  projectId: 'YOUR_PROJECT_ID',
  useWorker: true, // Default
});

If WebWorkers are unavailable (e.g., older browsers or restrictive CSP), the Beacon automatically falls back to main-thread execution.

Worker Requirements

Browser supports Worker API
Content Security Policy allows worker scripts
If using a bundler, ensure the worker script is included in the build output

Data Collectors

The Beacon uses pluggable collectors to gather detection signals:

Collector	Data Collected
`BrowserCollector`	User agent, screen size, language, timezone, plugins
`PerformanceCollector`	Page load timing, resource loading patterns

Collectors run automatically when the Beacon starts.

Browser Compatibility

Browser	Minimum Version	Worker Support
Chrome	60+	Yes
Firefox	55+	Yes
Safari	12+	Yes
Edge	79+	Yes
iOS Safari	12+	Yes
Android Chrome	60+	Yes

Offline Support

The Beacon handles intermittent connectivity:

When offline, events are queued in an OfflineQueue
Queue persists up to maxQueueSize events
When connectivity returns, queued events are sent automatically
Failed sends are retried with exponential backoff

Performance

Metric	Value
Page load impact	< 5ms
Bundle size	~41KB gzipped
Memory usage	~2MB typical
Network overhead	~1KB per detection event

Framework Integration

React

import { useEffect } from 'react';
import { AgentShieldBeacon } from '@kya-os/agentshield-beacon';

function App() {
  useEffect(() => {
    const beacon = new AgentShieldBeacon({
      projectId: process.env.NEXT_PUBLIC_CHECKPOINT_PROJECT_ID!,
    });
    beacon.start();

    return () => {
      beacon.destroy();
    };
  }, []);

  return <div>Your app</div>;
}

Vue

import { onMounted, onUnmounted } from 'vue';
import { AgentShieldBeacon } from '@kya-os/agentshield-beacon';

let beacon: AgentShieldBeacon;

onMounted(() => {
  beacon = new AgentShieldBeacon({
    projectId: import.meta.env.VITE_CHECKPOINT_PROJECT_ID,
  });
  beacon.start();
});

onUnmounted(() => {
  beacon?.destroy();
});

Beacon vs Pixel

For a lightweight, no-code alternative, see the Marketing Pixel.

Feature	Beacon	Pixel
Installation	npm package	Script tag / GTM
Detection depth	Advanced	Basic
Event tracking	Full	Limited
WebWorker	Yes	No
Offline support	Yes	No
Best for	Applications	Marketing sites

Next Steps

Marketing Pixel — Lightweight alternative for marketing sites
Dashboard Analytics — View detection data
Enforce — Add server-side enforcement

JavaScript Beacon

On this page