Installation

Client-side

The widget is a single self-contained JavaScript file — no dependencies, no build step, ~10 KB. It works anywhere that renders HTML. If you haven't installed it yet, start with the Installation guide; this page goes deeper into options, events and framework recipes.

Basic usage

html

<script src="https://your-instance.com/api/api.js" async></script>

<div data-sitekey="YOUR_SITE_KEY" class="ai-captcha"></div>

Place the div wherever you want the captcha badge to appear — inside your form is the usual spot. The script tag can live in <head> or anywhere on the page; it must be loaded over HTTPS when your site runs on HTTPS.

What it does

Starts collecting behavioral signals (mouse entropy, keystroke rhythm) on load.
Renders the badge and begins verification automatically once it enters the viewport (after a short data-collection window).
Injects <input type="hidden" name="ai-captcha-response"> next to the badge — this token travels with your form.
Intercepts form submission: if verification hasn't finished, it waits and shows a notice instead of submitting an unverifiable token.

Getting the response token

Three ways to read the token on the client:

Form submission — nothing to do; the hidden input ai-captcha-response is POSTed with the form.
Read the hidden input yourself: document.querySelector('input[name="ai-captcha-response"]').value.
Listen to the event — see below; e.detail.token carries it.

Options

Option	Where	Description
`data-sitekey`	div	Required. Your site key from the dashboard.
`data-api-url`	script tag	Override the API base URL. By default the widget derives it from the `src` of the script itself, so you normally never need this.

custom API URL

<script src="https://cdn.example.com/api.js"
        data-api-url="https://captcha.myservice.com/api" async></script>

Events

The widget dispatches an aicaptcha:verified DOM event (bubbles) on the widget element after the API responds:

listening for the result

document.querySelector('.ai-captcha')
  .addEventListener('aicaptcha:verified', (e) => {
    console.log('token:', e.detail.token);
    console.log('verified:', e.detail.verified);
    console.log('AI score:', e.detail.score); // 0..1, may be null
  });

Framework recipes

React / Next.js

app/contact/page.tsx (Next.js App Router)

import Script from "next/script";

export default function ContactPage() {
  return (
    <form action="/api/submit" method="post">
      <input name="email" type="email" required />
      <div data-sitekey={process.env.NEXT_PUBLIC_AICAPTCHA_SITE_KEY!} className="ai-captcha" />
      <button type="submit">Send</button>
    </form>
  );
}

// layout.tsx — load the script once:
// <Script src="https://your-instance.com/api/api.js" strategy="afterInteractive" />

Vue

ContactForm.vue

<template>
  <form @submit.prevent="submit">
    <input v-model="email" type="email" required />
    <div ref="captcha" data-sitekey="YOUR_SITE_KEY" class="ai-captcha"></div>
    <button type="submit">Send</button>
  </form>
</template>

<script setup>
const email = ref("");
function submit(e) {
  const token = e.target.querySelector('input[name="ai-captcha-response"]')?.value;
  if (!token) return alert("Please wait for verification.");
  // POST token to your backend...
}
</script>

WordPress

Add the script via your theme's functions.php, then use the shortcode or place the div inside any form:

functions.php

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script('aicaptcha', 'https://your-instance.com/api/api.js', [], null, true);
});

// Then inside any form template:
// <div data-sitekey="YOUR_SITE_KEY" class="ai-captcha"></div>

Styling

The badge ships with its own scoped styles (.ai-captcha-*) and needs no CSS from you. Wrap it in a container with padding if your design is tight.

Server side next: Server-side.