2. Add Quick Checks To Webpages

Introduction

Bot Buster Quick Checks can be placed anywhere on a website wherever there is an action that can be taken. These are button presses. Each Quick Check also must be associated with an email address somewhere on the page. This can be an email address contained in a text input or in another static HTML element. Due to this, 3 components are required and need to be set when adding a Quick Check. An email element id (data-email-element element containing the user’s email address), an action id (data-action-id button whose action will be protected by the Quick Check) and your company API key (data-api-key). The location where the Quick Check appears also must be included as a div element on the HTML page. The NPM installation is the easiest and fastest, but if you want a bit more flexibility with the widget there are also platform specific SDK integrations.

CDN Script URL

https://botbuste.b-cdn.net/prod/quick-check-inject-prod.js -> Connects to live production APIs

Your origin domain must be whitelisted. Requests from domains that are not whitelisted will be blocked.

Configuration Attributes Reference

Attribute	Required	Example	Purpose
id	Recommended	botbuster-script	Unique element identifier used by the SDK.
data-api-key	Yes	3ee57ddd-2946…	This is your company API key. It’s located at the top of the Quick Check Configurations Page within the portal.
data-action-id	Yes	login-form	This is the HTML element id of the button element which will launch the Quick Check for protection. Button can be submit, login, purchase item, create account and more.
data-email-element	Yes	auth-email	This is the HTML id of the field containing the email address. This can be a text input or a static HTML element.

NPM Package VS CDN Script Installation

	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

NPM Installation

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 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.

.ENV.LOCAL

"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'`).

React/Next.js Installation Code Examples

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.

Option B: Programmatic Control with `useBotbuster()` Hook

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

React Component Props Reference

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

"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>
  );
}

"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.

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>
  );
}

Installing The Quick Check Using a Direct SDK Integration

Overview & How It Works

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

Background SDK Information

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.

Implementation Instructions

Place the target render container <div id="botbuster-container"></div> inside your HTML form structure where you would like the Quick Check to appear.
Please add the required Quick Check SDK code into your website as shown below with specific code examples for Vanilla HTML/JS, Vue, Svelte, WordPress, WooCommerce, Angular and Shopify. Don’t forget to specify the Configuration Attributes that are required.

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

Vanilla HTML/JS, Svelte, Vue, WordPress, WooCommerce Code Examples

<!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>

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

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

<?php
// 1. Add BotBuster container to the login form by adding this snippet
// to your theme's functions.php or a custom site plugin

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
});

<?php
// 1. To protect WooCommerce customer account pages (/my-account)
// 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
        });
    }
});

Shopify Integration

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

{% 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 %}

Add the script right before </body> in layout/theme.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 %}

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

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`)

export {};

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

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);
  }
}

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

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

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.

  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

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`.

Once the code has been added, load your webpage and check that the Quick Check is showing when the button is pressed on the page. Then go to the third step Applying Rules To Quick Checks.

​Introduction

​CDN Script URL

​Configuration Attributes Reference

​NPM Package VS CDN Script Installation

​NPM Installation

​Step 1 - Install the package

​Step 2 - Add Your Key as an Environment Variable

​Step 3 - Import and Use

​Package Exports

​React/Next.js Installation Code Examples

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

​Option B: Programmatic Control with useBotbuster() Hook

​React Component Props Reference

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

​Installing The Quick Check Using a Direct SDK Integration

​Overview & How It Works

​Background SDK Information

​Implementation Instructions

​Vanilla HTML/JS, Svelte, Vue, WordPress, WooCommerce Code Examples

​Shopify Integration

​Step 1: Add Container to Customer Login Form

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

​Angular Integration

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

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

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

​JavaScript API Reference

​window.initBotbusterSDK(email)

​window.onBotbusterSuccess

​Security & CSP

​First-Party Cookie (bb_fcid)

​Content Security Policy (CSP) Directives

​Troubleshooting

Introduction

CDN Script URL

Configuration Attributes Reference

NPM Package VS CDN Script Installation

NPM Installation

Step 1 - Install the package

Step 2 - Add Your Key as an Environment Variable

Step 3 - Import and Use

Package Exports

React/Next.js Installation Code Examples

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

Option B: Programmatic Control with `useBotbuster()` Hook

React Component Props Reference

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

Installing The Quick Check Using a Direct SDK Integration

Overview & How It Works

Background SDK Information

Implementation Instructions

Vanilla HTML/JS, Svelte, Vue, WordPress, WooCommerce Code Examples

Shopify Integration

Step 1: Add Container to Customer Login Form

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

Angular Integration

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

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

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

JavaScript API Reference

window.initBotbusterSDK(email)

window.onBotbusterSuccess

Security & CSP

First-Party Cookie (bb_fcid)

Content Security Policy (CSP) Directives

Troubleshooting