JavaScript SDK – Reference

Constructor

const bb = new BlockBots(options)

Options

const bb = new BlockBots({
  apiKey: 'YOUR_API_KEY',
  retries: 2,
  delay: 1500,
  ui: false  // disable the overlay, handle the UI yourself
})

Methods

bb.verify()

Runs the verification flow and fires either onVerified or onBlocked.

Returns Promise<boolean> — true if verified as human, false if blocked or on error.

await bb.verify()

Flow:

1. If the __bb_decision cookie is present, the visitor is already blocked — stop
2. If the session cookies __bbst / __bbts are missing, collect signals and POST /v1/js
3. If the API returns status: 'challenge', show the captcha, submit the solution, and re-send the signals with the resulting captcha token
4. Wait for the session cookies (up to 3 s), then validate them against the API
5. On failure, retry from step 2 up to retries times, waiting delay ms between attempts

Call verify() once per page load. Visitors with valid session cookies are verified without re-fingerprinting.

bb.onVerified(callback)

Fires when the visitor is verified as human.

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

bb.onBlocked(callback)

Fires when the visitor is identified as a bot or verification does not succeed within retries. The callback receives a reason string (currently 'validation_failed').

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

bb.onError(callback)

Fires on an unexpected failure inside the flow (network error, invalid API key, bad server response). verify() then resolves to false.

bb.onError((error) => {
  console.error('Verification error:', error)
  // Recommended: fail open so legitimate users are not blocked
  showApp()
})

All three event methods return the instance, so the setup can be chained:

new BlockBots({ apiKey: 'YOUR_API_KEY', retries: 1 })
  .onVerified(() => document.getElementById('app').style.display = 'block')
  .onBlocked((reason) => console.log('Blocked:', reason))
  .onError((e) => console.error(e))
  .verify()

BlockBots.setLoaderBlocked() (static)

Shows the built-in overlay in its blocked state, independently of the verification flow.

BlockBots.setLoaderBlocked()

Captcha challenge

When the API is not confident about the visitor's IP (VPN, proxy, datacenter ranges) it responds with status: 'challenge' instead of a decision. The SDK then renders a proof-of-work captcha, submits the solution to the API, and retries the verification automatically with the returned captcha token. No integration work is required on your side — but keep the overlay enabled (ui: true) or provide your own visible container, otherwise the visitor cannot solve it.

Data collected

The SDK collects the following signals and sends them to the BlockBots API for analysis. No data is sold or shared with third parties.

Session cookies

After a successful verification the SDK stores session cookies so the visitor is not re-fingerprinted on the next page load. All cookies are set client-side with Secure and a 240-second lifetime.

Framework integration

Vue 3

// botcheck.js
import { BlockBots } from 'https://cdn.jsdelivr.net/gh/blockbots-org/blockbots-js@main/blockbots.esm.js'

export function runBotCheck() {
  return new Promise((resolve) => {
    const bb = new BlockBots({ apiKey: import.meta.env.VITE_BLOCKBOTS_KEY })
    bb.onVerified(() => resolve(true))
    bb.onBlocked(() => resolve(false))
    bb.onError(() => resolve(true)) // fail open
    bb.verify()
  })
}

<!-- App.vue -->
<script setup>
import { runBotCheck } from './botcheck'
const allowed = await runBotCheck()
</script>

React

// useBotCheck.js
import { useEffect, useState } from 'react'
import { BlockBots } from 'https://cdn.jsdelivr.net/gh/blockbots-org/blockbots-js@main/blockbots.esm.js'

export function useBotCheck(apiKey) {
  const [status, setStatus] = useState('pending') // 'pending' | 'verified' | 'blocked'

  useEffect(() => {
    const bb = new BlockBots({ apiKey })
    bb.onVerified(() => setStatus('verified'))
    bb.onBlocked(() => setStatus('blocked'))
    bb.onError(() => setStatus('verified')) // fail open
    bb.verify()
  }, [])

  return status
}