BlockBots

JavaScript SDK – Quick Start

Integrate BlockBots into any website in under 5 minutes using the JavaScript SDK.

Overview

The BlockBots JavaScript SDK runs in the browser and detects bots from canvas fingerprints, user agent, automation signals, pointer activity and IP address. It talks to the BlockBots API and tells you whether the visitor is a human or a bot.

Installation

The SDK ships in two builds:

BuildFileUsage
ES moduleblockbots.esm.jsimport inside <script type="module"> or a bundler
IIFEblockbots.min.jsclassic <script> tag, exposes the global BlockBots
<!-- ES module -->
<script type="module">
  import { BlockBots } from 'https://cdn.jsdelivr.net/gh/blockbots-org/blockbots-js@latest/blockbots.esm.js'
</script>

Basic usage

<script type="module">
  import { BlockBots } from 'https://cdn.jsdelivr.net/gh/blockbots-org/blockbots-js@latest/blockbots.esm.js'

  const bb = new BlockBots({
    apiKey: 'YOUR_API_KEY',
    retries: 1,
    delay: 1000,
    ui: true // built-in loading / blocked overlay
  })

  bb.onVerified(() => {
    // Human verified — allow the user to proceed
    console.log('Verified as human')
  })

  bb.onBlocked((reason) => {
    // Bot detected or verification failed
    console.log('Blocked:', reason)
  })

  await bb.verify()
</script>

Get your API key from the dashboard at panel.blockbots.org under Settings → API Keys.

How it works

  1. bb.verify() is called — the SDK collects browser signals
  2. Signals are sent to the BlockBots API (POST /v1/js)
  3. The API answers with one of three outcomes:
    • pass — session cookies are returned and stored in the browser
    • challenge — a captcha is shown (typical for VPN / low-confidence IPs); once solved, the signals are re-submitted with the captcha token
    • forbidden — confirmed bot, the __bb_decision cookie is set
  4. Cookies are validated against the API
  5. Your onVerified or onBlocked callback fires

Full example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My Site</title>
</head>
<body>

  <div id="app" style="display:none;">
    <!-- Protected content here -->
  </div>

  <script type="module">
    import { BlockBots } from 'https://cdn.jsdelivr.net/gh/blockbots-org/blockbots-js@main/blockbots.esm.js'

    const bb = new BlockBots({
      apiKey: 'YOUR_API_KEY',
      retries: 3,
      delay: 1000,
      ui: true
    })

    bb.onVerified(() => {
      document.getElementById('app').style.display = 'block'
    })

    bb.onBlocked((reason) => {
      console.log('Blocked:', reason)
    })

    bb.onError((error) => {
      console.error('BlockBots error:', error)
      // Fail open — show content even if detection fails
      document.getElementById('app').style.display = 'block'
    })

    await bb.verify()
  </script>

</body>
</html>

verify() never throws — errors are routed to onError and it resolves to false. The only exception is a missing apiKey, which throws from the constructor.

Next steps