Skip to content
WebDecoy Docs

Browser Client

@webdecoy/client is the client-side half of WebDecoy’s SDK story. It collects behavioral, environmental, and temporal signals in the browser, solves the proof-of-work challenge, and submits to your server — the self-hosted captcha endpoints mounted by the Express, Fastify, or Next.js packages. No third-party captcha script ever watches your visitors.

Prefer zero code? The Detection Script is a one-tag install with the full detection engine — the browser client is for teams who want the widget and signals under their own build.

Installation

Section titled “Installation”
Terminal window
npm install @webdecoy/client

The Captcha Widget

Section titled “The Captcha Widget”
import { WebDecoyCaptcha } from '@webdecoy/client';


WebDecoyCaptcha.configure({
  serverUrl: 'https://your-server.com'
});


// Checkbox widget
WebDecoyCaptcha.render('captcha-box', {
  siteKey: 'YOUR_SITE_KEY', // publishable org ID (UUID) from the Enforcement page
  callback: (token) => submit(token)
});


// Or protect a form invisibly
WebDecoyCaptcha.invisible({ siteKey: 'YOUR_SITE_KEY' });

Three modes:

ModeBehavior
CheckboxRenders the familiar widget in a container element
InvisibleAttaches to a form and solves in the background
On-demandTrigger the flow programmatically when you choose

The token the widget produces goes to your backend, which verifies it with captcha.verifyToken(token, ip) from the Node SDK.

What It Collects

Section titled “What It Collects”

The widget gathers the signals the detection engine scores — behavioral (mouse and interaction patterns), environmental (browser and device characteristics), and temporal (timing consistency) — and binds them into the proof-of-work, so a bot can’t skip the collection and still solve the challenge.

Session Clearance

Section titled “Session Clearance”

The browser check that session clearance builds on is this same prove-you’re-a-real-browser flow: passing it is how a session earns clearance on enforced routes.

For most sites you don’t need the captcha at all — silent minting earns the token during normal browsing. Either drop in the standalone script with your site key:

<script async src="https://cdn.webdecoy.com/client/webdecoy.global.js"
        data-site-key="YOUR_SITE_KEY"></script>

or call it programmatically:

import { startClearance } from '@webdecoy/client';


startClearance({ siteKey: 'YOUR_SITE_KEY' });

Minting posts the site key plus a device fingerprint to POST /api/v1/clearance and sets the wd_clearance cookie at browser idle — at most once per session, no proof-of-work, no page-load cost.

Next Steps

Section titled “Next Steps”