Skip to main content

​
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

  1. Go to Partner Dashboard → Integrations → Cloudflare Turnstile
  2. Enter your Turnstile Site Key and Secret Key
  3. 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: {
//     botshield_user_id: "uuid-...",
//     auth_mode: "private",
//     ...
//   }
// }

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

​
Behavioral Fingerprint (Client-Side)

Runs over a 1.5-second collection window inside an isolated context.
SignalPointsWhat It Catches
navigator.webdriver = true+40Puppeteer, Playwright, Selenium
No browser plugins+10Headless browsers
Zero hardware concurrency+15Virtual environments
No mouse or touch events+15Non-interactive client
Screen dimensions 0x0+20Headless browser default
Canvas fingerprint blocked+10Headless or privacy extension
No WebGL renderer+15No GPU access

​
Score Ranges

ScoreRisk LevelRecommended Action
0-30LowSilent pass — no UI shown to user
31-70Gray zoneBotShield passkey verification as escalation
71-99HighActive passkey challenge required
100Definitive botHard 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