Skip to main content

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)
The Client SDK requires a site key (pk_live_...), which you create in the BotShield Partner Dashboard under Settings > Site Keys.

Two Integration Modes

How It Works

Web Component Flow

1. Merchant page loads <botshield-verify>
2. User clicks "Verify human presence"
3. BotShield verification opens (new tab)
4. User completes passkey challenge
5. Widget updates to "Human presence verified"
6. onsuccess callback fires with signed token
7. Merchant server validates token

iframe Flow

1. Merchant page embeds iframe from cdn.botshield.ai/challenge
2. Cloudflare edge scores the request (ASN, TLS, headers)
3. iframe runs behavioral fingerprint (canvas, WebGL, mouse, timing)
4. Combined score determines pass/fail
5. postMessage sends result to parent page

Quick Start

<!-- 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 -- enable checkout
    document.querySelector('[name=checkout]').disabled = false;

    // Send 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

ScenarioRecommended ModeWhy
Checkout protection (Shopify, WooCommerce)Web ComponentPasskey verification = highest assurance
Cart page gatingiframePassive, no user friction for low-risk traffic
High-value drops / limited releasesWeb ComponentEvery buyer must prove human presence
General bot screeningiframeAutomated scoring filters most bots silently
API-driven integrationsServer SDKBackend-to-backend, no UI component

Site Keys

Site keys are public/secret key pairs created in the Partner Dashboard:
KeyPrefixWhere UsedCan Do
Public / Site Keypk_live_Frontend data-site-keyIdentify merchant, safe to expose
Secret Keysk_live_Backend / server onlyVerify 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