BotBuster Docs
v1.2.0

Frontend Installation Documentation

Complete integration guidelines for installing and configuring the BotBuster Quick Check (QC) SDK across modern web platforms.

Overview & How It Works

The BotBuster Quick Check (QC) SDK is a lightweight client-side library engineered for real-time bot mitigation and email verification.

  • Automatic Input Binding: Listens to designated email fields to verify addresses dynamically as users type.
  • Responsive Layout Modes: Adapts UI rendering based on the client viewport.
    • Desktop: Renders an inline, non-intrusive container (#botbuster-container).
    • Mobile & Tablet: Displays a full-screen, touch-optimized modal dialog.
  • First-Party Security Cookie: Issues a 30-minute session cookie (bb_fcid) upon successful challenge completion, ensuring cross-browser persistence.
  • Event Handlers: Triggers window.onBotbusterSuccess() instantly upon verification.

CDN Script URLs & Environments

Environment CDN Script URL Notes
Production https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js Connects to live production API services.
Development https://botbuste.b-cdn.net/dev/quick-check-inject.js Sandboxed environment for local testing.

Security Requirement

Your origin domain must be registered under your application profile in the BotBuster Administrative Dashboard. Requests from unwhitelisted domains will halt execution.

NPM Package Installation

botbuster-captcha

If your project uses a bundler (Vite, Webpack, Next.js, Turbopack, etc.), install the official botbuster-captcha package instead of adding the CDN <script> tag manually. The package loads the SDK for you, is safe to import during server-side rendering, and ships with TypeScript definitions.

Step 1: Install the Package

Terminal 
# npm
npm install botbuster-captcha

# yarn
yarn add botbuster-captcha

# pnpm
pnpm add botbuster-captcha

# bun
bun add botbuster-captcha

Step 2: Add Your API Key as an Environment Variable

Keep the API key out of your source code by reading it from an environment variable. The key is used in the browser, so it needs the public prefix your framework requires.

.env.local 
# Next.js
NEXT_PUBLIC_BOTBUSTER_API_KEY=YOUR_BOTBUSTER_API_KEY

# Vite (React, Vue, Svelte)
VITE_BOTBUSTER_API_KEY=YOUR_BOTBUSTER_API_KEY

Step 3: Import and Use

Import the component or hook in any client component. See the React / Next.js Integration section for complete login form examples.

TSX / JSX 
"use client";
import { BotbusterCaptcha } from 'botbuster-captcha';

export function Captcha({ email }: { email: string }) {
  return (
    <BotbusterCaptcha
      apiKey={process.env.NEXT_PUBLIC_BOTBUSTER_API_KEY!}
      actionId="login"
      email={email}
      onSuccess={(data) => console.log(data.submissionTrackingId)}
    />
  );
}

Package Exports

Export Type Purpose
BotbusterCaptcha Component Drop-in captcha bound to an email value.
useBotbuster Hook Programmatic control: trigger, isVerified, submissionTrackingId.
BotbusterProvider Component Configures apiKey and actionId once for the whole app.
reportLogin Function Reports the final login outcome ('success' or 'failure').

NPM Package vs. CDN Script

NPM Package CDN Script
Best for React / Next.js apps with a build step Plain HTML, CMS platforms, other frameworks
Script loading Handled by the package Manual <script> tag
Configuration Component props data-* attributes
TypeScript types Included Not included

Domain Registration Still Required

The NPM package calls the same BotBuster services as the CDN script, so your origin domain must still be registered in the BotBuster Administrative Dashboard.

Configuration Attributes Reference

Attribute Required Example Purpose
id Recommended botbuster-script Unique element identifier used by the SDK.
data-api-key Yes 3ee57ddd-2946... Client authentication key.
data-action-id Yes login-form Custom label categorizing the user flow.
data-email-element Yes auth-email Target HTML id of the email input field.

Quick Start (Vanilla HTML)

Place the target render container <div id="botbuster-container"></div> inside your HTML form structure.

HTML 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Sign In</title>
</head>
<body>
  <form id="login-form">
    <h2>Sign In</h2>
    
    <label for="email">Email</label>
    <input type="email" id="email" name="email" required />
    
    <label for="password">Password</label>
    <input type="password" id="password" name="password" required />
    
    <!-- BotBuster Captcha Container -->
    <div id="botbuster-container"></div>
    
    <button type="submit" id="submit-btn" disabled>Sign In</button>
  </form>

  <!-- 1. Define Success Event Callback -->
  <script>
    window.onBotbusterSuccess = function() {
      console.log("[BotBuster] Verification completed successfully.");
      document.getElementById("submit-btn").disabled = false;
    };
  </script>

  <!-- 2. Embed SDK Script -->
  <script
    id="botbuster-script"
    src="https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js"
    data-api-key="YOUR_BOTBUSTER_API_KEY"
    data-action-id="login-form"
    data-email-element="email"
    async>
  </script>
</body>
</html>

Angular Integration

In Angular, manage the script dynamically within a component's lifecycle hooks (ngOnInit and ngOnDestroy).

Step 1: Add Global Typings (src/types/botbuster.d.ts)

TypeScript 
export {};

declare global {
  interface Window {
    onBotbusterSuccess?: (() => void) | null;
    initBotbusterSDK?: (email: string, sessionId?: string | null, forceSync?: boolean) => void;
  }
}

Step 2: Angular Component (login.component.ts)

TypeScript 
import { Component, OnInit, OnDestroy } from '@angular/core';
import { CommonModule } from '@angular/common';
import { FormsModule } from '@angular/forms';

@Component({
  selector: 'app-login',
  standalone: true,
  imports: [CommonModule, FormsModule],
  templateUrl: './login.component.html',
  styleUrls: ['./login.component.css']
})
export class LoginComponent implements OnInit, OnDestroy {
  email: string = '';
  password: string = '';
  isVerified: boolean = false;
  isSubmitting: boolean = false;

  private readonly SCRIPT_ID = 'botbuster-script';
  private readonly SCRIPT_URL = 'https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js';
  private readonly API_KEY = 'YOUR_BOTBUSTER_API_KEY';

  ngOnInit(): void {
    // 1. Set global success callback
    window.onBotbusterSuccess = () => {
      this.isVerified = true;
      this.isSubmitting = false;
      console.log('[BotBuster] Verification completed.');
    };

    // 2. Inject the SDK Script if not already loaded
    if (!document.getElementById(this.SCRIPT_ID)) {
      const script = document.createElement('script');
      script.id = this.SCRIPT_ID;
      script.src = this.SCRIPT_URL;
      script.async = true;
      script.setAttribute('data-api-key', this.API_KEY);
      script.setAttribute('data-action-id', 'angular-login');
      script.setAttribute('data-email-element', 'angular-email');
      script.setAttribute('data-web-url', window.location.href);
      document.body.appendChild(script);
    }
  }

  ngOnDestroy(): void {
    // Cleanup script and callback on navigation
    const script = document.getElementById(this.SCRIPT_ID);
    if (script) {
      script.remove();
    }
    window.onBotbusterSuccess = null;
  }

  onSubmit(): void {
    if (!this.isVerified) {
      if (this.email && window.initBotbusterSDK) {
        this.isSubmitting = true;
        window.initBotbusterSDK(this.email.trim());
      }
      return;
    }

    // Backend verifies the first-party `bb_fcid` cookie
    console.log('Form submitted with verified email:', this.email);
  }
}

Step 3: Component Template (login.component.html)

HTML 
<form (ngSubmit)="onSubmit()" class="auth-form">
  <h2>Sign In</h2>

  <div class="form-group">
    <label for="angular-email">Email</label>
    <input
      id="angular-email"
      type="email"
      name="email"
      [(ngModel)]="email"
      placeholder="user@example.com"
      required
    />
  </div>

  <div class="form-group">
    <label for="angular-password">Password</label>
    <input
      id="angular-password"
      type="password"
      name="password"
      [(ngModel)]="password"
      required
    />
  </div>

  <!-- BotBuster Mount Container -->
  <div id="botbuster-container"></div>

  <button type="submit" [disabled]="!isVerified && isSubmitting">
    {{ isVerified ? 'Sign In' : isSubmitting ? 'Verifying...' : 'Verify & Sign In' }}
  </button>
</form>

Svelte / SvelteKit Integration

In Svelte (Svelte 4/5 or SvelteKit), initialize the script inside onMount so it runs exclusively in the browser.

Svelte 
<script>
  import { onMount, onDestroy } from 'svelte';
  import { browser } from '$app/environment';

  let email = '';
  let password = '';
  let isVerified = false;
  let isVerifying = false;

  const SCRIPT_URL = 'https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js';
  const API_KEY = 'YOUR_BOTBUSTER_API_KEY';

  onMount(() => {
    if (!browser) return;

    // 1. Assign success callback
    window.onBotbusterSuccess = () => {
      isVerified = true;
      isVerifying = false;
    };

    // 2. Inject script
    if (!document.getElementById('botbuster-script')) {
      const script = document.createElement('script');
      script.id = 'botbuster-script';
      script.src = SCRIPT_URL;
      script.async = true;
      script.setAttribute('data-api-key', API_KEY);
      script.setAttribute('data-action-id', 'svelte-login');
      script.setAttribute('data-email-element', 'svelte-email');
      script.setAttribute('data-web-url', window.location.href);
      document.body.appendChild(script);
    }
  });

  onDestroy(() => {
    if (!browser) return;
    const script = document.getElementById('botbuster-script');
    if (script) script.remove();
    window.onBotbusterSuccess = null;
  });

  function handleSubmit() {
    if (!isVerified) {
      if (email && window.initBotbusterSDK) {
        isVerifying = true;
        window.initBotbusterSDK(email.trim());
      }
      return;
    }
    // Submit form credentials
    console.log('Submitting authenticated request...');
  }
</script>

<form on:submit|preventDefault={handleSubmit} class="login-box">
  <h2>Sign In</h2>

  <label for="svelte-email">Email</label>
  <input
    id="svelte-email"
    type="email"
    bind:value={email}
    placeholder="name@example.com"
    required
  />

  <label for="password">Password</label>
  <input
    id="password"
    type="password"
    bind:value={password}
    required
  />

  <!-- BotBuster inline container -->
  <div id="botbuster-container"></div>

  <button type="submit" disabled={!isVerified && isVerifying}>
    {isVerified ? 'Sign In' : isVerifying ? 'Verifying...' : 'Verify & Sign In'}
  </button>
</form>

React / Next.js Integration

Official NPM Package

Integrate BotBuster seamlessly into React 18/19 and Next.js (App Router & Pages Router) using the official botbuster-captcha package. It eliminates manual <script> tag management, handles SSR safety, provides responsive modals, and offers full TypeScript support out of the box.

Step 1: Install the Package

Terminal 
npm install botbuster-captcha
# or
yarn add botbuster-captcha
# or
pnpm add botbuster-captcha

Option A: Drop-in Component (<BotbusterCaptcha />)

Best for standard login and signup forms. Automatically binds to the input and displays the inline container on desktop or full-screen modal on mobile devices.

TSX / JSX 
"use client";
import React, { useState } from 'react';
import { BotbusterCaptcha } from 'botbuster-captcha';
export default function LoginForm() {
  const [email, setEmail] = useState('');
  const [isVerified, setIsVerified] = useState(false);
  return (
    <form onSubmit={handleSubmit} className="login-form">
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter your email"
        required
      />
      {/* BotBuster Captcha Component */}
      <BotbusterCaptcha
        apiKey="YOUR_BOTBUSTER_API_KEY"
        actionId="react-login"
        email={email}
        onSuccess={(data) => {
          console.log('[BotBuster] Solved! Tracking ID:', data.submissionTrackingId);
          setIsVerified(true);
        }}
      />
      <button type="submit" disabled={!isVerified}>
        Sign In
      </button>
    </form>
  );
}

Option B: Programmatic Control with useBotbuster() Hook

Best for custom validation pipelines, multi-step flows, or reporting login results directly to BotBuster after backend verification.

TSX / JSX 
"use client";
import React, { useState } from 'react';
import { useBotbuster, reportLogin } from 'botbuster-captcha';
export default function AuthPage() {
  const [email, setEmail] = useState('');
  const [loading, setLoading] = useState(false);
  const { trigger, isVerified, submissionTrackingId } = useBotbuster({
    apiKey: 'YOUR_BOTBUSTER_API_KEY',
    actionId: 'custom-login',
    onSuccess: (data) => {
      console.log('Passed captcha challenge:', data.submissionTrackingId);
    }
  });
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    // 1. Trigger captcha if not yet verified
    if (!isVerified) {
      const passed = await trigger(email);
      if (!passed) {
        setLoading(false);
        return;
      }
    }
    // 2. Send submissionTrackingId to your backend
    try {
      const res = await fetch('/api/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, trackingId: submissionTrackingId }),
      });
      // 3. Report final authentication outcome to BotBuster
      reportLogin(res.ok ? 'success' : 'failure');
    } catch {
      reportLogin('failure');
    } finally {
      setLoading(false);
    }
  };
  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="user@example.com"
      />
      {/* Container where desktop inline challenge attaches */}
      <div id="botbuster-container" />
      <button type="submit" disabled={loading}>
        {loading ? 'Verifying...' : 'Log In'}
      </button>
    </form>
  );
}

Next.js App Router Setup (<BotbusterProvider />)

Wrap your root layout to configure the API key globally. Child components can then use <BotbusterCaptcha /> without re-declaring credentials.

app/layout.tsx 
import { BotbusterProvider } from 'botbuster-captcha';
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <BotbusterProvider apiKey="YOUR_BOTBUSTER_API_KEY" actionId="login">
          {children}
        </BotbusterProvider>
      </body>
    </html>
  );
}

React Component Props Reference

Prop Type Default Description
apiKey string Context / Required Your client authentication key.
actionId string undefined Flow identifier (e.g., 'login', 'checkout').
email string undefined Current email state. Auto-triggers verification upon valid format.
onSuccess (data) => void undefined Callback returning submissionTrackingId upon passing.
containerId string botbuster-container ID of the mount element on desktop.

Vue 3 / Nuxt 3 Integration

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

const email = ref('');
const isVerified = ref(false);

onMounted(() => {
  window.onBotbusterSuccess = () => {
    isVerified.value = true;
  };

  if (!document.getElementById('botbuster-script')) {
    const script = document.createElement('script');
    script.id = 'botbuster-script';
    script.src = "https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js";
    script.setAttribute('data-api-key', 'YOUR_API_KEY');
    script.setAttribute('data-email-element', 'user-email');
    document.body.appendChild(script);
  }
});

onUnmounted(() => {
  window.onBotbusterSuccess = null;
  const script = document.getElementById('botbuster-script');
  if (script) script.remove();
});
</script>

<template>
  <form>
    <input id="user-email" type="email" v-model="email" required />
    
    <div id="botbuster-container"></div>
    
    <button type="submit" :disabled="!isVerified">Submit</button>
  </form>
</template>

Shopify Integration

In Shopify, add the script and container to your customer login and registration templates.

Step 1: Add Container to Customer Login Form

In your Shopify theme editor, navigate to sections/main-login.liquid or templates/customers/login.liquid and find the customer login form block:

Liquid 
{% form 'customer_login' %}
  ...
  <div class="field">
    <input
      type="email"
      name="customer[email]"
      id="CustomerEmail"
      autocomplete="email"
      autocorrect="off"
      autocapitalize="off"
      placeholder="{{ 'customer.login_page.email' | t }}"
      required
    >
    <label for="CustomerEmail">{{ 'customer.login_page.email' | t }}</label>
  </div>

  <!-- 1. Add BotBuster Container inside the form -->
  <div id="botbuster-container" style="margin: 15px 0;"></div>

  <button type="submit" id="CustomerLoginSubmit">
    {{ 'customer.login_page.sign_in' | t }}
  </button>
{% endform %}

Step 2: Inject Script in theme.liquid or Login Template

Add the script right before </body> in layout/theme.liquid:

Liquid 
{% if template contains 'customers' %}
  <script>
    window.onBotbusterSuccess = function() {
      console.log("[BotBuster] Customer verified successfully.");
      var btn = document.getElementById("CustomerLoginSubmit");
      if (btn) btn.disabled = false;
    };
  </script>
  <script
    id="botbuster-script"
    src="https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js"
    data-api-key="YOUR_BOTBUSTER_API_KEY"
    data-action-id="shopify-customer-login"
    data-email-element="CustomerEmail"
    async>
  </script>
{% endif %}

Tip

Setting data-email-element="CustomerEmail" matches Shopify’s default customer email input ID. If using customer registration (customers/register.liquid), pass RegisterForm-email.

WordPress / WooCommerce Integration

You can integrate BotBuster into WordPress using functions.php or a custom site plugin.

Option A: Protect Standard WordPress Login (wp-login.php)

Add this snippet to your theme's functions.php:

PHP 
<?php
// 1. Add BotBuster container to the login form
add_action('login_form', function() {
    echo '<div id="botbuster-container" style="margin-bottom: 16px;"></div>';
});

// 2. Enqueue BotBuster SDK script on the login screen
add_action('login_enqueue_scripts', function() {
    ?>
    <script>
        window.onBotbusterSuccess = function() {
            var submitBtn = document.getElementById('wp-submit');
            if (submitBtn) submitBtn.disabled = false;
        };
    </script>
    <script
        id="botbuster-script"
        src="https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js"
        data-api-key="YOUR_BOTBUSTER_API_KEY"
        data-action-id="wp-login"
        data-email-element="user_login"
        async>
    </script>
    <?php
});

Option B: WooCommerce Login / Registration Form

To protect WooCommerce customer account pages (/my-account):

PHP 
<?php
// 1. Insert container into WooCommerce login form
add_action('woocommerce_login_form', function() {
    echo '<div id="botbuster-container" style="margin: 15px 0;"></div>';
});

// 2. Load script on the WooCommerce account page
add_action('wp_enqueue_scripts', function() {
    if (is_account_page() && !is_user_logged_in()) {
        add_action('wp_footer', function() {
            ?>
            <script>
                window.onBotbusterSuccess = function() {
                    var submitBtn = document.querySelector('button[name="login"]');
                    if (submitBtn) submitBtn.disabled = false;
                };
            </script>
            <script
                id="botbuster-script"
                src="https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js"
                data-api-key="YOUR_BOTBUSTER_API_KEY"
                data-action-id="woocommerce-login"
                data-email-element="username"
                async>
            </script>
            <?php
        });
    }
});

JavaScript API Reference

window.initBotbusterSDK(email)

Programmatically forces execution of the verification pipeline for a given email parameter.

window.initBotbusterSDK("user@domain.com");

window.onBotbusterSuccess

Callback handler invoked immediately upon successful user verification. The SDK clears this function reference post-execution.

Security & CSP

First-Party Cookie (bb_fcid)

Upon successfully passing the challenge, the SDK sets a secure, first-party cookie on the active domain root to prevent cross-site tracking blocks.

Set-Cookie: bb_fcid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; Path=/; Max-Age=1800; SameSite=Lax; Secure

Content Security Policy (CSP) Directives

To comply with strict web security policies, adjust your standard HTTP headers:

Content-Security-Policy: script-src 'self' https://botbuste.b-cdn.net; connect-src 'self' https://api-live.botbuster.io; frame-src https://quickcheck.botbuster.io https://dev.botbuster.io;

Troubleshooting & Diagnostics

Log / Problem Description Resolution Strategy
[Botbuster SDK] Domain is not whitelisted. Add current domain (including localhost origins) inside the API dashboard.
HTTP 403 on /initSDK Verify data-api-key string matches provided production credentials.
Script does not load on input focus Add explicit type="email" or bind via data-email-element.