BotSigged SDK - Real-time bot detection via WebSocket
A lightweight SDK for real-time bot detection via WebSocket to be connected to botsigged.com (account required).
The SDK uses code splitting to minimize initial load time. Optional features are lazy-loaded only when enabled.
| File | Size | Gzipped | When Loaded |
|------|------|---------|-------------|
| index.js | 66 KB | 17 KB | Always (initial) |
| challenge-*.js | 6 KB | 2 KB | Only if action: 'challenge' |
| hash-*.js | 9 KB | 4 KB | Only if hashVerification.enabled |
| File | Size | Gzipped |
|------|------|---------|
| botsigged.js | 85 KB | 25 KB |
The IIFE build includes all features in a single file for simplicity.
- Lightweight - ~17 KB gzipped initial bundle (ESM)
- Code splitting - Challenge and hash modules lazy-loaded on demand
- Modular architecture:
- Mouse, scroll, and form behavior tracking
- Browser fingerprinting
- WebSocket transport (Phoenix channels)
- Form protection (optionally auto-blocks bots before detection completes)
- PoW challenge system (optional)
``bash`
npm install @botsigged/sdk
Or include directly in HTML:
`html`
`typescript
import { BotSigged } from '@botsigged/sdk';
const botsigged = new BotSigged({
apiKey: 'pk_your_api_key_here',
});
`
The SDK auto-starts and begins collecting behavioral signals immediately.
Track risk across sessions by associating a user account:
`typescript
const botsigged = new BotSigged({
apiKey: 'pk_your_api_key_here',
accountId: 'user_123', // Associate session with account on init
});
// Or identify later (e.g., after login)
await botsigged.identify({ accountId: 'user_123' });
`
Pass the session ID to your backend for server-side score lookup:
`typescript
const botsigged = new BotSigged({
apiKey: 'pk_your_api_key_here',
// Option 1: Cookie (for traditional form posts)
cookie: true, // Sets '_bsid' cookie
// Option 2: Headers (for SPAs using fetch/XHR)
headers: true, // Adds 'X-BotSigged-ID' header to requests
// Option 3: Hidden form field (cookie-free forms)
formInject: true, // Injects '_bsid' hidden input
});
`
Then verify on your backend:
`
GET https://api.botsigged.com/v1/sessions/{session_id}
Authorization: Bearer sk_your_secret_key
Automatically hold form submissions until bot detection completes:
`typescript`
const botsigged = new BotSigged({
apiKey: 'pk_your_api_key_here',
formProtection: {
mode: 'holdUntilReady', // Wait for score before allowing submit
maxHoldTime: 3000, // Max 3s wait
},
});
For programmatic form submissions:
`typescript
const botsigged = new BotSigged({ apiKey: 'pk_your_api_key_here' });
// Wait for detection before submitting
const handleSubmit = async (data) => {
const { score, timedOut } = await botsigged.waitUntilReady();
if (score && score > 70) {
return; // Block suspicious submissions
}
await fetch('/api/submit', {
method: 'POST',
body: JSON.stringify(data),
});
};
`
Automatically block or challenge high-scoring sessions:
`typescript``
const botsigged = new BotSigged({
apiKey: 'pk_your_api_key_here',
action: 'block', // or 'challenge' for PoW
actionThreshold: 70, // Score threshold
});
MIT