> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Client SDK Embed

> Drop-in web component for merchant-side human presence verification and bot detection

# Client SDK Embed

The BotShield Client SDK is a lightweight web component (`<botshield-verify>`) that merchants embed directly on their pages to gate checkout, cart, and other sensitive flows behind human presence verification.

**CDN:** `https://cdn.botshield.ai/sdk.js` (\~9KB minified)

<Info>
  The Client SDK requires a **site key** (`pk_live_...`), which you create in the BotShield Partner Dashboard under **Settings > Site Keys**.
</Info>

## Two Integration Modes

<CardGroup cols={2}>
  <Card title="Web Component" icon="shield-check" href="/embed/web-component">
    Active human verification via BotShield passkey flow. User clicks the widget, completes a passkey challenge, and receives a signed verification token.
  </Card>

  <Card title="Signal Pixel" icon="signal" href="/embed/signal-pixel">
    Passive signal collection. Enable `signals="true"` on the web component to run edge scoring and behavioral fingerprinting silently. Low-risk traffic passes automatically; high-risk is escalated.
  </Card>
</CardGroup>

## How It Works

### Web Component Flow

```
1. Merchant page loads <botshield-verify>
2. User clicks "Verify human with BotShield"
3. BotShield verification opens (QR modal or new tab)
4. User completes the passkey / biometric challenge
5. Widget resolves to one of: Human Verified, MultiPass Active, or Human Unavailable
6. onsuccess callback fires with the PII-free verification_token
7. Merchant server validates the token (signature only — no identity inside)
```

### Signal Pixel Flow

```
1. Merchant page loads <botshield-verify signals="true">
2. Cloudflare edge scores the request (ASN, TLS, headers)
3. Component runs behavioral fingerprint (canvas, WebGL, mouse, timing)
4. Combined score determines pass/fail
5. Events deliver result to your code
```

## Quick Start

```html theme={null}
<!-- Load the SDK -->
<script src="https://cdn.botshield.ai/sdk.js"></script>

<!-- Add the verification widget -->
<botshield-verify
  site-key="pk_live_YOUR_SITE_KEY"
  theme="auto"
  onsuccess="onBotShieldVerified"
  onfailure="onBotShieldFailed"
></botshield-verify>

<script>
  function onBotShieldVerified({ token }) {
    // Human Verified (or MultiPass Active) -- enable checkout
    document.querySelector('[name=checkout]').disabled = false;

    // Send the PII-free verification_token to your server for validation
    fetch('/api/verify-botshield', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token }),
    });
  }

  function onBotShieldFailed({ reason }) {
    console.error('BotShield verification failed:', reason);
  }
</script>
```

## When to Use Which Mode

| Scenario                                   | Recommended Mode                    | Why                                            |
| ------------------------------------------ | ----------------------------------- | ---------------------------------------------- |
| Checkout protection (Shopify, WooCommerce) | Web Component                       | Passkey verification = highest assurance       |
| Cart page gating                           | Signal Pixel                        | Passive, no user friction for low-risk traffic |
| High-value drops / limited releases        | Web Component                       | Every buyer must prove human presence          |
| General bot screening                      | Signal Pixel                        | Automated scoring filters most bots silently   |
| API-driven integrations                    | [Server SDK](/sdk/client-libraries) | Backend-to-backend, no UI component            |

## Site Keys

Site keys are public/secret key pairs created in the Partner Dashboard:

| Key               | Prefix     | Where Used                    | Can Do                               |
| ----------------- | ---------- | ----------------------------- | ------------------------------------ |
| Public / Site Key | `pk_live_` | Frontend `site-key` attribute | Identify merchant, safe to expose    |
| Secret Key        | `sk_live_` | Backend / server only         | Validate tokens, call management API |

* `pk_test_` / `sk_test_` for sandbox environments
* `pk_live_` / `sk_live_` for production
* Public keys are domain-locked at creation (stolen keys are unusable on other domains)

Create and manage site keys at **Settings > Site Keys** in the Partner Dashboard.

## Next Steps

<CardGroup cols={2}>
  <Card icon="code" href="/embed/web-component" title="Web Component Reference">
    Full attribute API, events, states, and integration examples
  </Card>

  <Card icon="signal" href="/embed/signal-pixel" title="Signal Pixel Reference">
    Bot scoring details, signal collection, and configuration
  </Card>

  <Card icon="flask" href="https://console.botshield.ai" title="Try in Playground">
    Test both modes live in the Partner Dashboard playground
  </Card>

  <Card icon="github" href="https://github.com/Bot-Shield/botshield-sdk-embed" title="Source Code">
    View the SDK source on GitHub
  </Card>
</CardGroup>