This guide adds explainable bot detection to a Next.js app in about ten minutes. The browser is fingerprinted by the collector tag; your backend (or middleware) fetches a verdict by session token and decides whether to allow, challenge or block. See the live demo for what the signals look like.

1. Add the collector tag

Load the collector on every page so visitors get a session token. In app/layout.tsx (App Router):

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://detectip.ai/collector.js" data-key="pk_live_..." />
      </body>
    </html>
  );
}

The collector sets a first-party botd_token cookie and exposes window.__BOTD_TOKEN__.

2. Fetch the verdict server-side

Never call the verdict API from the browser with your secret key. Do it in a route handler. app/api/guard/route.ts:

export async function POST(req: Request) {
  const { token } = await req.json();
  const r = await fetch(
    `https://detectip.ai/api/v1/verdict?token=${encodeURIComponent(token)}`,
    { headers: { "X-API-Key": process.env.DETECTIP_KEY! } }
  );
  if (!r.ok) return Response.json({ action: "allow" }); // fail open
  const v = await r.json();
  return Response.json({ action: v.action, score: v.score, band: v.band });
}

3. Gate a sensitive action

Before a signup, checkout or comment POST, check the verdict and act on the server-recommended action (allow / challenge / block):

const token = (document.cookie.match(/botd_token=([^;]+)/) || [])[1];
const { action } = await fetch("/api/guard", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token }),
}).then((r) => r.json());

if (action === "block") showError("Request blocked.");
else if (action === "challenge") showProofOfWork();
else submitForm();

4. Or enforce in Middleware

For route-wide protection, call the verdict from middleware.ts using the cookie. Keep timeouts short and fail open so a slow API never takes your site down. For latency-sensitive paths, prefer gating specific actions (step 3) over every request.

Why this beats a User-Agent check

A spoofed User-Agent is free. detectip.ai scores the TLS (JA4), HTTP/2 frames, IP intelligence and behavior together, so a Chrome UA on a non-browser stack is caught. Every verdict lists the signals — see how to filter bots from web traffic.

FAQ

Will this block Googlebot? No — declared crawlers are verified via reverse DNS; legitimate search bots aren't flagged as fake. See fraud prevention.

What about latency? Fetch the verdict server-to-server and fail open on timeout. Gate high-value actions rather than every page.

Where do I get a key? Free tier, no card: get an API key. Full reference: API docs.