`<botshield-verify>` Web Component

The <botshield-verify> element is BotShield’s client-side orchestration layer. It renders a verification widget on the merchant’s page and coordinates up to three layers of defense:

Passkey Verification (always on) — cryptographic human proof via device biometrics
Signal Pixel (opt-in via signals="true") — passive behavioral fingerprinting and edge scoring
Third-party Integrations (automatic) — Cloudflare Turnstile, reCAPTCHA, and more when configured in your dashboard Integrations settings

On success, the widget fires a callback with a PII-free verification_token, an opaque signal_token (tamper-proof bot score), and any third-party results.

Anonymous by construction. The widget never collects or returns identity. The verification_token claims are only { request_id, verified, organization_id, timestamp, nonce } — no email, no user id, no device data. The widget resolves to one of three result states: Human Verified, MultiPass Active, or Human Unavailable.

Installation

Add a single script tag to your page. No npm install, no build step.

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

The script registers the <botshield-verify> custom element globally. It uses a closed Shadow DOM so it never conflicts with your page styles.

Quick Start

<botshield-verify
  site-key="pk_live_YOUR_SITE_KEY"
  theme="auto"
  signals="true"
  onsuccess="handleVerified"
  onfailure="handleFailed"
></botshield-verify>

<script>
  function handleVerified({ token, signal_token, signal_score, turnstile_token }) {
    // Send ALL signals to your backend for server-side validation
    fetch('/api/verify-checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        botshield_token: token,         // Signed verification JWT
        signal_token: signal_token,     // Tamper-proof bot score (validate server-side)
        // signal_score is display-only — always use signal_token for security
      }),
    });
  }

  function handleFailed({ reason }) {
    console.error('Verification failed:', reason);
  }
</script>

Attributes

Attribute	Type	Default	Description
`site-key`	string	required	Your public site key (`pk_live_...` or `pk_test_...`)
`scope`	string	—	The Census scope this verification is bound to (e.g. `checkout.complete`). Required to enable the MultiPass pre-check fast path — when set, a MultiPass-Active user resolves instantly without a QR or Face ID prompt.
`theme`	`light` \| `dark` \| `auto`	`auto`	Visual theme. `auto` follows the user’s `prefers-color-scheme`.
`signals`	`true` \| `false`	`false`	Enable BotShield Signal Pixel — collects device and behavioral signals silently via an invisible 1x1 embed. Returns a tamper-proof `signal_token` alongside the bot score.
`scan-mode`	`modal` \| `redirect`	`modal`	How the QR scan UI is presented when a desktop user needs to verify on their phone. `modal` shows the QR code as an overlay. `redirect` opens a full-page verification screen.
`platform`	string	—	An opaque label for the surface initiating verification (e.g. `shopify`). Threaded through for attribution only — never identity.
`platform-user-ref`	string	—	An opaque partner reference (your own user id or a hashed equivalent) used to resolve a MultiPass linkage. Never identity — no email, no name. Hashed with a server secret before storage.
`link-on-verify`	`true` \| `false`	`true`	Whether a successful verification writes a MultiPass linkage tying `platform-user-ref` to the user’s BotShield credential. Set `false` to opt out.
`challenge-url`	string	`https://cdn.botshield.ai/challenge`	Override the challenge page URL (for self-hosted deployments).
`onsuccess`	string	—	Name of a global function called on success with `{ token, signal_token, signal_score, turnstile_token }`
`onfailure`	string	—	Name of a global function called on failure with `{ reason }`
`onexpired`	string	—	Name of a global function called when the verification expires
`onready`	string	—	Name of a global function called when the widget loads

The token passed to onsuccess is the PII-free verification_token. On a MultiPass fast-path success it may be null (no challenge token is minted) — listen for botshield:multipass-status if you need to distinguish the MultiPass Active result. There is no identity in any callback payload.

Events

In addition to callback attributes, the element dispatches standard Custom Events:

const el = document.querySelector('botshield-verify');

el.addEventListener('botshield:success', (e) => {
  const { token, signal_token, signal_score, turnstile_token } = e.detail;
  submitToServer(token, signal_token);
});

el.addEventListener('botshield:failure', (e) => {
  console.error('Failed:', e.detail.reason);
});

Event	`e.detail`	Description
`botshield:ready`	`{}`	Widget has loaded and is ready for interaction
`botshield:multipass-status`	`{ event_id, verdict, reason, result_state }`	Fires after the MultiPass pre-check (when `scope` is set). `result_state` ∈ `human_verified` \| `multipass_active` \| `not_verified` \| `unavailable`.
`botshield:success`	`{ token, signal_token, signal_score, turnstile_token }`	Resolved positive (Human Verified or MultiPass Active). `token` is the PII-free `verification_token` (may be `null` on a MultiPass fast-path pass).
`botshield:failure`	`{ reason }`	Resolved Human Unavailable. `reason` is an opaque code — the underlying cause is never exposed across the boundary.
`botshield:expired`	`{}`	The verification expired before completion. Widget resets to idle.
`botshield:reset`	`{}`	Widget was reset to idle state.

Signal Pixel

When signals="true", an invisible 1x1 iframe collects behavioral fingerprints alongside the verification widget: Edge signals (server-side, can’t be spoofed):

Datacenter ASN detection
TLS fingerprint analysis
HTTP protocol version
IP velocity tracking
Header anomaly detection

Behavioral signals (client-side):

WebDriver / automation flags
Canvas fingerprint
WebGL renderer
Mouse / touch events
Screen & hardware profile

The combined score (0–100) is returned in the signal_score field. However, this client-side score can be spoofed via DevTools. For tamper-proof validation, use the signal_token:

// Client-side score (display only — can be spoofed)
console.log('Bot score:', e.detail.signal_score); // 13

// Tamper-proof token (validate server-side — can't be spoofed)
console.log('Signal token:', e.detail.signal_token); // "bs_sig_a1b2c3..."

See the Signal Pixel reference for score ranges and signal details.

Third-Party Integrations

BotShield automatically loads and validates third-party bot detection tools when configured in your dashboard Integrations settings.

Cloudflare Turnstile

When Turnstile is enabled for your organization:

The web component loads the Turnstile script automatically
An invisible Turnstile widget runs in the background
The Turnstile token is collected and returned in e.detail.turnstile_token
BotShield validates the token server-side using your stored secret key
The pass/fail result is included in your verification confidence score

No code changes required — just enable Turnstile in your dashboard and add your keys. Recommended Turnstile settings:

Widget Mode: Invisible — BotShield handles all UI
Pre-clearance: Yes — let verified visitors bypass lower CF challenges
Pre-clearance Level: Interactive (high) — BotShield provides the real biometric proof

Adding More Integrations

reCAPTCHA, DataDome, HUMAN, and more are coming. Each integration follows the same pattern: configure in your dashboard, BotShield auto-loads and validates. Contact us to request an integration.

Server-Side Validation

Never trust client-side state alone. The widget appearance, signal_score, and even the token must be validated on your server. BotShield provides three levels of server-side validation.

1. Verify the Verification Token

The primary check — validate the signed, PII-free verification_token that proves a human completed the challenge. No shared secret is needed: BotShield holds the signing key, so the token itself is the proof.

const response = await fetch('https://api.botshield.ai/operations/sdk/verify-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: requestBody.botshield_token,
  }),
});

const { data } = await response.json();
// {
//   valid: true,
//   claims: {
//     request_id: "req_...",        // your join key
//     verified: true,
//     organization_id: "org_...",
//     timestamp: "2026-06-16T12:00:00Z",
//     nonce: "..."                  // anti-replay
//     // anonymous by construction — NO email, user id, or device data
//   }
// }

if (!data.valid || !data.claims.verified) {
  // Human Unavailable — apply your own policy
}

2. Validate the Signal Token (tamper-proof bot score)

If you’re using the Signal Pixel (signals="true"), validate the signal_token to get the real server-side bot score:

const response = await fetch('https://api.botshield.ai/v1/validate-signal', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_live_YOUR_SECRET_KEY',
  },
  body: JSON.stringify({
    signal_token: requestBody.signal_token,
  }),
});

const result = await response.json();
// {
//   valid: true,
//   score: 13,              // Server-side score (can't be spoofed)
//   edge_score: 10,         // Network-layer signals
//   client_score: 16,       // Behavioral fingerprint
//   country: "US",
//   fp_hash: "a1b2c3..."   // Fingerprint for correlation
// }

Signal tokens are one-time use and expire after 10 minutes. The signal_score in the client event is for display only — always use signal_token for security decisions.

3. Combined Confidence Score

When all signals are present, BotShield combines them into a single confidence score:

// Full server-side validation with all signals
const response = await fetch('https://api.botshield.ai/v1/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_live_YOUR_SECRET_KEY',
  },
  body: JSON.stringify({
    token: requestBody.botshield_token,
    signal_token: requestBody.signal_token,
  }),
});

const result = await response.json();
// {
//   valid: true,
//   confidence: 0.97,
//   signals: {
//     botshield_score: 13,
//     turnstile: { success: true },
//     passkey: { verified: true }
//   }
// }

if (result.valid && result.confidence >= 0.5) {
  // Human verified — proceed with checkout
} else {
  // Suspected bot — block or require additional verification
}

Visual States

The widget transitions through five states, mapping to the three Census result states:

State	Result state	Appearance	Behavior
idle	—	Robot icon, “Verify human with BotShield”	Click to start verification
verifying	—	Spinner, “Verifying…”	Verification in progress
verified	Human Verified	Green checkmark, “Presence Live”, green border	Resolved. Token available via callback.
multipass_active	MultiPass Active	Green card icon, “MultiPass Active”, outlined green border	Resolved via the MultiPass fast path.
failed	Human Unavailable	Red X, “Presence Unavailable”, red border	Click to reset and retry.

The visual state is derived client-side from the anonymous result — it is not a transmitted field. The cause of a Human Unavailable result (failed presence vs. infrastructure) is never distinguished at the partner boundary.

Themes

Light
Dark
Auto

White background (#f9f9f9), gray border (#bebfc1), dark text.

Dark background (#0b0b0c), subtle border (#2a2a2a), light text. Blue gradient BotShield logo.

Follows the user’s system preference via prefers-color-scheme.

JavaScript API

`BotShield.render()` — Programmatic Rendering

Create and mount a verification widget from JavaScript. Works with SPAs (React, Vue, Angular) and anywhere you need programmatic control.

const widget = BotShield.render('#checkout-container', {
  siteKey: 'pk_live_YOUR_SITE_KEY',
  signals: true,
  theme: 'dark',
  scanMode: 'modal',
  onSuccess: ({ token, signal_token, signal_score }) => {
    // Send to your backend
    submitToServer(token, signal_token);
  },
  onFailure: ({ reason }) => {
    console.error('Verification failed:', reason);
  },
  onReady: () => {
    console.log('Widget loaded');
  },
});

Options:

Option	Type	Description
`siteKey`	string	required — Your public site key
`theme`	`'light'` \| `'dark'` \| `'auto'`	Visual theme (default: `'auto'`)
`signals`	boolean	Enable Signal Pixel (default: `false`)
`scanMode`	`'modal'` \| `'redirect'`	QR scan presentation (default: `'modal'`)
`challengeUrl`	string	Override challenge URL
`onSuccess`	function	Called with `{ token, signal_token, signal_score, turnstile_token }`
`onFailure`	function	Called with `{ reason }`
`onExpired`	function	Called when token expires
`onReady`	function	Called when widget loads

Returns a widget handle:

// Trigger verification programmatically
widget.verify();

// Get the token after verification
const token = widget.getToken();     // string | null

// Get the Signal Pixel score
const score = widget.getScore();     // number | null

// Reset to idle state
widget.reset();

// Remove widget from DOM
widget.destroy();

// Access the underlying element
widget.element;  // <botshield-verify> HTMLElement

Direct Element Access

If you prefer HTML attributes, you can also query the element directly:

const el = document.querySelector('botshield-verify');
el.verify();
el.getToken();
el.getScore();
el.reset();

Framework Examples

React:

import { useEffect, useRef } from 'react';

function CheckoutVerification() {
  const containerRef = useRef(null);
  const widgetRef = useRef(null);

  useEffect(() => {
    widgetRef.current = BotShield.render(containerRef.current, {
      siteKey: 'pk_live_YOUR_KEY',
      signals: true,
      onSuccess: ({ token, signal_token }) => {
        fetch('/api/checkout', {
          method: 'POST',
          body: JSON.stringify({ token, signal_token }),
        });
      },
    });
    return () => widgetRef.current?.destroy();
  }, []);

  return <div ref={containerRef} />;
}

Vue 3:

<template>
  <div ref="container" />
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';

const container = ref(null);
let widget = null;

onMounted(() => {
  widget = BotShield.render(container.value, {
    siteKey: 'pk_live_YOUR_KEY',
    signals: true,
    onSuccess: ({ token, signal_token }) => {
      submitCheckout(token, signal_token);
    },
  });
});

onUnmounted(() => widget?.destroy());
</script>

QR Scan Mode

When a desktop user needs to verify on their phone (cross-device flow), the scan-mode attribute controls the presentation:

<botshield-verify site-key="pk_..." scan-mode="modal" />

Shows a QR code overlay on the current page with:

BotShield logo and step-by-step instructions
QR code for phone scanning
“Waiting for verification…” status with auto-close on completion
Cancel button

Redirect

<botshield-verify site-key="pk_..." scan-mode="redirect" />

Opens a full-page verification screen in a new tab.

Form Integration

When placed inside a <form>, the widget automatically injects a hidden input with the verification token:

<form action="/checkout" method="POST">
  <botshield-verify
    site-key="pk_live_YOUR_SITE_KEY"
    signals="true"
    onsuccess="enableSubmit"
  ></botshield-verify>

  <!-- These hidden inputs are auto-created on verification success -->
  <!-- <input type="hidden" name="botshield_token" value="eyJhbGc..."> -->

  <button type="submit" id="checkout-btn" disabled>
    Proceed to Checkout
  </button>
</form>

<script>
  function enableSubmit() {
    document.getElementById('checkout-btn').disabled = false;
  }
</script>

Platform Examples

Shopify (Cart Page)

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

<botshield-verify
  site-key="pk_live_YOUR_KEY"
  theme="auto"
  signals="true"
  onsuccess="enableCheckout"
></botshield-verify>

<script>
  function enableCheckout({ token, signal_token }) {
    sessionStorage.setItem('botshield_token', token);
    sessionStorage.setItem('botshield_signal', signal_token);
    document.querySelector('[name=checkout]').disabled = false;
  }
</script>

WooCommerce

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

<botshield-verify
  site-key="pk_live_YOUR_KEY"
  theme="light"
  signals="true"
  onsuccess="onVerified"
></botshield-verify>

<script>
  function onVerified({ token, signal_token }) {
    const form = document.querySelector('form.checkout');

    const tokenInput = document.createElement('input');
    tokenInput.type = 'hidden';
    tokenInput.name = 'botshield_token';
    tokenInput.value = token;
    form.appendChild(tokenInput);

    const signalInput = document.createElement('input');
    signalInput.type = 'hidden';
    signalInput.name = 'botshield_signal_token';
    signalInput.value = signal_token;
    form.appendChild(signalInput);

    document.getElementById('place_order').disabled = false;
  }
</script>

Escalation Pattern (with existing bot detection)

Use BotShield alongside your existing bot detection tool. Only show the verification widget when your existing tool is uncertain:

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

<botshield-verify
  id="bs-verify"
  site-key="pk_live_YOUR_KEY"
  signals="true"
  style="display: none;"
></botshield-verify>

<script>
  // Your existing bot detection (Turnstile, DataDome, etc.)
  const riskScore = await getExternalBotScore();

  if (riskScore < 0.3) {
    // Clearly human — let through without BotShield
    proceedToCheckout();
  } else if (riskScore > 0.9) {
    // Clearly bot — block
    showBlockedMessage();
  } else {
    // Gray zone — escalate to BotShield
    document.getElementById('bs-verify').style.display = 'block';
  }
</script>

Next Steps

Signal Pixel Reference — Passive bot scoring details, score ranges, signal sources
Integrations — Configure Cloudflare Turnstile and other providers
Site Keys — Create and manage keys in the dashboard
Server SDK — Backend token validation libraries

Get Started

Client SDK Embed

Server SDK

Integration Guides

Deployment

Queue (Q)

Concepts

Web Component

`<botshield-verify>` Web Component

Installation

Quick Start

Attributes

Events

Signal Pixel

Third-Party Integrations

Cloudflare Turnstile

Adding More Integrations

Server-Side Validation

1. Verify the Verification Token

2. Validate the Signal Token (tamper-proof bot score)

3. Combined Confidence Score

Visual States

Themes

JavaScript API

`BotShield.render()` — Programmatic Rendering

Direct Element Access

Framework Examples

QR Scan Mode

Redirect

Form Integration

Platform Examples

Shopify (Cart Page)

WooCommerce

Escalation Pattern (with existing bot detection)

Next Steps

​<botshield-verify> Web Component

​Installation

​Quick Start

​Attributes

​Events

​Signal Pixel

​Third-Party Integrations

​Cloudflare Turnstile

​Adding More Integrations

​Server-Side Validation

​1. Verify the Verification Token

​2. Validate the Signal Token (tamper-proof bot score)

​3. Combined Confidence Score

​Visual States

​Themes

​JavaScript API

​BotShield.render() — Programmatic Rendering

​Direct Element Access

​Framework Examples

​QR Scan Mode

​Modal (default)

​Redirect

​Form Integration

​Platform Examples

​Shopify (Cart Page)

​WooCommerce

​Escalation Pattern (with existing bot detection)

​Next Steps

`<botshield-verify>` Web Component

Installation

Quick Start

Attributes

Events

Signal Pixel

Third-Party Integrations

Cloudflare Turnstile

Adding More Integrations

Server-Side Validation

1. Verify the Verification Token

2. Validate the Signal Token (tamper-proof bot score)

3. Combined Confidence Score

Visual States

Themes

JavaScript API

`BotShield.render()` — Programmatic Rendering

Direct Element Access

Framework Examples

QR Scan Mode

Modal (default)

Redirect

Form Integration

Platform Examples

Shopify (Cart Page)

WooCommerce

Escalation Pattern (with existing bot detection)

Next Steps