JavaScript Beacon

Overview

The AgentShield JavaScript Beacon is a lightweight, high-performance library for detecting AI agents and bots in web applications. With advanced WebWorker support and intelligent batching, it provides real-time protection with minimal impact on your application's performance.

Key Features

Performance Optimized

• < 5ms page load impact - Non-blocking execution
• 41KB gzipped - Lightweight bundle size
• WebWorker support - Offload processing from main thread
• Automatic batching - Efficient network usage
• Compression - Reduces bandwidth consumption

Advanced Detection

• Multi-signal analysis - Combines multiple detection methods
• Real-time scoring - Instant confidence scores
• Behavioral tracking - Monitors interaction patterns
• Session continuity - Tracks agents across pages

Developer Friendly

• TypeScript support - Full type definitions included
• Framework agnostic - Works with any JavaScript framework
• Extensive API - Rich set of methods for custom implementations
• Debug mode - Detailed logging for development
• Error recovery - Automatic retry and fallback mechanisms

How It Works

The beacon operates in three modes, automatically selecting the best option:

1. WebWorker Mode (Preferred)

   • Runs detection in a separate thread
   • Zero impact on UI performance
   • Handles batching and compression

2. Fallback Mode (Compatibility)

   • Uses requestIdleCallback for non-blocking execution
   • Maintains performance on older browsers
   • Graceful degradation

3. Direct Mode (Simple)

   • Synchronous execution for critical events
   • Immediate detection results
   • Best for time-sensitive operations

Use Cases

E-commerce Protection

Protect product information, pricing, and inventory data from scrapers:

beacon.trackEvent('product_view', {
  productId: 'SKU123',
  price: 29.99,
  protected: true
});

Content Protection

Prevent AI agents from accessing premium content:

beacon.trackEvent('content_access', {
  articleId: 'premium-123',
  subscription: 'required'
});

API Security

Monitor and protect API endpoints from automated access:

beacon.trackEvent('api_call', {
  endpoint: '/api/data',
  method: 'GET'
});

Form Protection

Detect automated form submissions:

beacon.trackEvent('form_submit', {
  formType: 'registration',
  fields: ['email', 'password']
});

Browser Compatibility

Fully Supported

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

Limited Support

• Older browsers fall back to compatibility mode
• IE11 supported with polyfills (not recommended)

Architecture Benefits

Intelligent Batching

Events are automatically batched to reduce network requests:

• Configurable batch size (1-100 events)
• Time-based flushing (default: 5 seconds)
• Priority-based processing
• Automatic deduplication

Offline Support

The beacon handles network interruptions gracefully:

• Events queued when offline
• Automatic retry with exponential backoff
• Persistent storage with IndexedDB/LocalStorage
• Guaranteed delivery when connection restored

Privacy & Compliance

Built with privacy in mind:

• GDPR compliant
• Respects Do Not Track headers
• No PII collection by default
• Configurable data retention
• IP anonymization options

Performance Impact

Typical performance metrics:

Integration Options

NPM Package

Best for modern build tools and frameworks:

npm install @kya-os/agentshield-beacon

CDN

For quick integration without build tools:

<script src="https://cdn.jsdelivr.net/npm/@kya-os/agentshield-beacon/dist/beacon.min.js"></script>

ES Modules

For modern browsers with module support:

import { AgentShieldBeacon } from 'https://cdn.skypack.dev/@kya-os/agentshield-beacon';

Comparison with Alternatives

Quick Example

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

// Initialize with your configuration
const beacon = new AgentShieldBeacon({
  apiKey: 'your-api-key',
  batchSize: 20,
  flushInterval: 5000,
  useWorker: true,
  debug: false
});

// Track page views
beacon.collect('pageview');

// Track custom events
beacon.trackEvent('user_action', {
  action: 'button_click',
  value: 'signup'
});

// Clean up when done
window.addEventListener('beforeunload', () => {
  beacon.destroy();
});

Next Steps

• Installation Guide - Detailed setup instructions
• Basic Usage - Common implementation patterns
• API Reference - Complete API documentation
• Configuration - Advanced configuration options
• Worker Mode - Optimize with WebWorkers