Getting Started with BotSigged

BotSigged is a real-time bot detection system that analyzes user behavior to distinguish humans from automated traffic. It provides continuous risk scoring throughout user sessions, enabling you to take action against bots while minimizing friction for legitimate users.

How It Works

BotSigged uses a lightweight JavaScript SDK that runs in your users’ browsers. The SDK:

1. Collects behavioral signals - Observes how users interact with your page
2. Sends data via WebSocket - Real-time communication for immediate scoring
3. Receives risk scores - Your application gets updated scores as behavior is analyzed
4. Protects forms automatically - Optional built-in protection against instant bot submissions

All analysis happens server-side. The SDK only collects raw interaction data - it doesn’t make detection decisions locally, making it harder for bots to reverse-engineer.

Quick Start

1. Create a Site

Create a team and add a site in the BotSigged dashboard. You’ll receive an API key for your site.

2. Add the SDK

The simplest integration is a single script tag. The SDK auto-starts and begins protecting your site immediately:

<script src="https://unpkg.com/@botsigged/sdk/dist/botsigged.js"></script>
<script>
  const botsigged = BotSigged.init({
    apiKey: 'your-site-api-key'
  });
</script>

That’s it! With default settings, the SDK will:

• Connect to BotSigged via WebSocket
• Begin collecting behavioral signals
• Hold form submissions until a detection score is available
• Send you real-time score updates

3. React to Bot Scores

Listen for score updates to take action when bots are detected:

const botsigged = BotSigged.init({
  apiKey: 'your-site-api-key',
  onScoreUpdate: (score) => {
    console.log('Bot score:', score.bot_score);
    console.log('Classification:', score.classification);
  }
});

4. Configure Automatic Actions (Optional)

For many use cases, you can let BotSigged handle bot mitigation automatically:

BotSigged.init({
  apiKey: 'your-site-api-key',
  actionThreshold: 70,
  action: 'challenge'  // Require proof-of-work for suspected bots
});

Integration Options

Script Tag (Recommended for most sites)

Best for traditional websites, WordPress, landing pages, and sites where you want zero-code protection:

<script src="https://unpkg.com/@botsigged/sdk/dist/botsigged.js"></script>
<script>
  BotSigged.init({ apiKey: 'your-api-key' });
</script>

ES Module (For bundled applications)

Best for React, Vue, Next.js, and other modern JavaScript applications:

import { BotSigged } from '@botsigged/sdk';

const sdk = new BotSigged({
  apiKey: 'your-api-key',
  autoStart: false  // Control when tracking starts
});

// Start when ready
sdk.start();

Bundle Size

The SDK uses code splitting to minimize initial load time. Optional features are lazy-loaded only when enabled.

ESM Build (npm package)

File	Size	Gzipped	When Loaded
index.js	85 KB	18 KB	Always (initial)
challenge-*.js	10 KB	2.8 KB	Only if action: 'challenge'
hash-*.js	14 KB	5.1 KB	Only if hashVerification.enabled

For most integrations, the initial bundle is only 18 KB gzipped.

IIFE Build (script tag)

File	Size	Gzipped
botsigged.js	470 KB	116 KB

The IIFE build includes all features in a single file for simplicity.

What Gets Tracked

BotSigged observes common user interactions:

• Mouse activity - Movement patterns and clicks
• Scrolling - How users navigate the page
• Form interactions - Typing patterns and field navigation
• Browser environment - Device and browser characteristics

The SDK is designed to be lightweight and non-intrusive. It doesn’t:

• Record keystrokes or form values (only timing patterns)
• Take screenshots
• Track across different domains
• Store personal information

Next Steps

• Configuration - Customize SDK behavior
• API Reference - Explore the full SDK API
• React Integration - SPA-specific patterns