BotShield Signal Pixel

The BotShield Signal Pixel is an opt-in passive signal collection layer built into the <botshield-verify> web component. When enabled with signals="true", it combines edge scoring, behavioral fingerprinting, and third-party integrations (Cloudflare Turnstile) to produce a tamper-proof bot score — without requiring any user interaction.

The Signal Pixel is not a separate integration. It is a capability of the same <botshield-verify> web component used for active passkey verification. Add signals="true" to enable it.

Three Layers of Defense

The Signal Pixel is Layer 1 of BotShield’s defense-in-depth architecture:

Quick Start

<script src="https://cdn.botshield.ai/sdk.js"></script>

<botshield-verify
  site-key="pk_live_YOUR_KEY"
  signals="true"
  onsuccess="handleVerified"
></botshield-verify>

<script>
  function handleVerified({ token, signal_token, signal_score }) {
    // signal_score = display only (can be spoofed via DevTools)
    // signal_token = tamper-proof (validate server-side)
    fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify({
        botshield_token: token,
        signal_token: signal_token,
      }),
    });
  }
</script>

Or with BotShield.render():

const widget = BotShield.render('#container', {
  siteKey: 'pk_live_YOUR_KEY',
  signals: true,
  onSuccess: ({ token, signal_token, signal_score, turnstile_token }) => {
    submitToServer(token, signal_token);
  },
});

Tamper-Proof Signal Tokens

The signal_score returned in the client event is for display only. It can be spoofed via DevTools. Always validate using the signal_token on your server.

The Signal Pixel returns an opaque signal_token (e.g. bs_sig_a1b2c3...) alongside the display score. This token maps to the real score stored in BotShield’s database — it cannot be faked.

Server-Side Validation

import BotShield from 'botshield-sdk';

const client = new BotShield({ apiKey: process.env.BOTSHIELD_API_KEY });

// Validate the signal token — get the REAL score
const signal = await client.sdk.validateSignal({
  signal_token: req.body.signal_token,
});

if (signal.valid) {
  console.log('Server-side score:', signal.score); // 13 (can't be spoofed)
  console.log('Country:', signal.country);          // "US"
  console.log('Fingerprint:', signal.fp_hash);      // "a1b2c3..."
}

Signal tokens are one-time use and expire after 10 minutes. Once validated, the token is consumed and cannot be reused.

Cloudflare Turnstile Integration

When you enable Cloudflare Turnstile in your BotShield dashboard, the web component automatically loads and runs Turnstile alongside the Signal Pixel. No code changes needed.

Setup

Go to Partner Dashboard → Integrations → Cloudflare Turnstile
Enter your Turnstile Site Key and Secret Key
Click Save

Recommended Turnstile settings:

Widget Mode: Invisible — BotShield handles all UI
Pre-clearance: Yes
Pre-clearance Level: Interactive (high)

That’s it. The web component detects the configuration and loads Turnstile automatically on every page load.

Combined Confidence Scoring

When you pass both token and signal_token to verify-token, BotShield returns a combined confidence score that factors in all available signals:

const result = await client.sdk.verifyToken({
  token: req.body.botshield_token,
  signal_token: req.body.signal_token,
});

// result = {
//   valid: true,
//   confidence: 0.97,
//   signals: {
//     botshield_score: 13,              // Signal Pixel (0-100)
//     turnstile: { success: true },     // Cloudflare Turnstile
//     passkey: { verified: true },      // Biometric proof
//   },
//   claims: {
//     request_id: "req_...",
//     verified: true,
//     // anonymous attestation — no identity in the token
//   }
// }

Scoring Method

The bot score is a combined metric from two independent layers:

combined_score = (edge_score × 0.5) + (behavioral_score × 0.5)

Edge Scoring (Server-Side — Can’t Be Spoofed)

Evaluated at the Cloudflare Worker edge before any HTML is served.

Signal	Points	What It Catches
Datacenter ASN	+35	Traffic from AWS, GCP, Azure, DigitalOcean
TLS version not 1.3	+20	Scripts or outdated tooling
Stripped TLS ClientHello (under 200 bytes)	+15	Automated HTTP library
Padded TLS ClientHello (over 1000 bytes)	+10	Evasion technique
HTTP/1.1 protocol	+15	curl, scripts, old bots
Missing or bot User-Agent	+30-40	python, curl, puppeteer, selenium
Missing Accept headers	+10-15	Non-browser clients
High IP velocity (>20 req/min)	+20-30	Automated rapid requests

Behavioral Fingerprint (Client-Side)

Runs over a 1.5-second collection window inside an isolated context.

Signal	Points	What It Catches
`navigator.webdriver` = true	+40	Puppeteer, Playwright, Selenium
No browser plugins	+10	Headless browsers
Zero hardware concurrency	+15	Virtual environments
No mouse or touch events	+15	Non-interactive client
Screen dimensions 0x0	+20	Headless browser default
Canvas fingerprint blocked	+10	Headless or privacy extension
No WebGL renderer	+15	No GPU access

Score Ranges

Score	Risk Level	Recommended Action
0-30	Low	Silent pass — no UI shown to user
31-70	Gray zone	BotShield passkey verification as escalation
71-99	High	Active passkey challenge required
100	Definitive bot	Hard block — no challenge offered

Full Escalation Flow

The most powerful pattern — passive Signal Pixel screening with automatic escalation to passkey verification when the score is ambiguous:

<botshield-verify
  id="bs"
  site-key="pk_live_KEY"
  signals="true"
  scan-mode="modal"
  onsuccess="onVerified"
></botshield-verify>

<script>
  function onVerified({ token, signal_token, signal_score }) {
    if (signal_score <= 30) {
      // Low risk — proceed without passkey
      submitOrder(token, signal_token);
    } else {
      // Gray zone or high risk — passkey already completed
      submitOrder(token, signal_token);
    }
  }
</script>

Security

Signal collection runs in an isolated context — cannot access the parent page’s DOM, cookies, or storage
signal_token is tamper-proof — always validate server-side, never trust signal_score alone
Behavioral fingerprint collects device/environmental signals only — no PII, no tracking
Turnstile secret keys are stored encrypted and used server-side only — never exposed to the client

Next Steps

Web Component Reference

Full API docs for <botshield-verify> and BotShield.render()

API Reference

Backend SDK methods for server-side validation

Enable Turnstile

Configure integrations in your Partner Dashboard

Playground

Test Signal Pixel + Turnstile with live scoring

Get Started

Client SDK Embed

Server SDK

Integration Guides

Deployment

Queue (Q)

Concepts

BotShield Signal Pixel

BotShield Signal Pixel

Three Layers of Defense

Quick Start

Tamper-Proof Signal Tokens

Server-Side Validation

Cloudflare Turnstile Integration

Setup

Combined Confidence Scoring

Scoring Method

Edge Scoring (Server-Side — Can’t Be Spoofed)

Behavioral Fingerprint (Client-Side)

Score Ranges

Full Escalation Flow

Security

Next Steps

Web Component Reference

API Reference

Enable Turnstile

Playground

​BotShield Signal Pixel

​Three Layers of Defense

​Quick Start

​Tamper-Proof Signal Tokens

​Server-Side Validation

​Cloudflare Turnstile Integration

​Setup

​Combined Confidence Scoring

​Scoring Method

​Edge Scoring (Server-Side — Can’t Be Spoofed)

​Behavioral Fingerprint (Client-Side)

​Score Ranges

​Full Escalation Flow

​Security

​Next Steps

Web Component Reference

API Reference

Enable Turnstile

Playground

BotShield Signal Pixel

Three Layers of Defense

Quick Start

Tamper-Proof Signal Tokens

Server-Side Validation

Cloudflare Turnstile Integration

Setup

Combined Confidence Scoring

Scoring Method

Edge Scoring (Server-Side — Can’t Be Spoofed)

Behavioral Fingerprint (Client-Side)

Score Ranges

Full Escalation Flow

Security

Next Steps