Skip to main content
HumanKey
Wersja polska →

Documentation

Integration guides for WordPress, JavaScript, REST API, and webhooks.

On this page

Quick Start

Most setups take under 2 minutes. Choose the method that fits your platform:

Quick Setup

→WordPress Plugin~2 min→1-Line JS Snippet~60 secRECOMMENDED

Developer / Server-Side

→REST API~20 min→AI Crawler RulesAfter setup

Need real-time notifications? Webhooks are available after tracking is live (Business & Enterprise).

WordPress Plugin

The official HumanKey plugin installs directly from the WordPress plugin directory.

  1. 1Go to your WordPress Admin → Plugins → Add New
  2. 2Search for "HumanKey" and click Install Now
  3. 3Activate the plugin
  4. 4Navigate to Settings → HumanKey
  5. 5Paste your Site Public Key (found in your Dashboard → Sites)
  6. 6Save — the tracking snippet is now live on all pages

What the plugin adds

  • • Injects the HumanKey tracking snippet in your site's <head>
  • • Adds an AI Traffic dashboard panel in WP Admin
  • • Shows live bot/human traffic stats without leaving WordPress
  • • Displays your HumanKey Verified badge status

1-Line JS Install

Works on any platform that allows custom HTML: Shopify, Webflow, Squarespace, static sites, and custom apps.

<!-- Add to your <head> tag -->

<script async src="https://api.humankey.io/api/detect.js?key=YOUR_PUBLIC_KEY"></script>

Replace YOUR_PUBLIC_KEY with your site's public key from the Dashboard → Sites page.

Platform-specific guides

  • • Shopify: Settings → Themes → Edit Code → theme.liquid → paste in <head>
  • • Webflow: Project Settings → Custom Code → Head Code
  • • Squarespace: Settings → Advanced → Code Injection → Header
  • • Custom HTML: Paste before the closing </head> tag

Next.js (App Router)

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://api.humankey.io/api/detect.js?key=YOUR_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

React SPA (Create React App / Vite)

// App.tsx or index.tsx
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.humankey.io/api/detect.js?key=YOUR_KEY';
    script.async = true;
    document.head.appendChild(script);
    return () => { document.head.removeChild(script); };
  }, []);

  return <div>{/* Your app */}</div>;
}

Google Tag Manager (Custom HTML Tag)

<script>
  (function() {
    var s = document.createElement('script');
    s.src = 'https://api.humankey.io/api/detect.js?key=YOUR_KEY';
    s.async = true;
    document.head.appendChild(s);
  })();
</script>
<!-- Trigger: All Pages -->

Nuxt 3

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://api.humankey.io/api/detect.js?key=YOUR_KEY',
          async: true,
        },
      ],
    },
  },
});

REST API (Server-Side)

Use the REST API from your server to detect bots and AI crawlers before serving content. Ideal for Next.js middleware, Laravel, Django, or any server-side framework.

Bot Detection — POST /api/detect

// Request

POST https://api.humankey.io/api/detect
Content-Type: application/json

{
  "siteKey": "pk_...",
  "url": "https://yoursite.com/article",
  "referrer": "https://google.com"
}

// Response

{
  "isHuman": false,
  "action": "block"
}
// Detailed bot analytics (name, company, confidence)
// available in your Dashboard → Analytics.

The action field tells you what to do: block → return 429, monitor → log and continue, allow → explicitly permitted crawler.

Next.js Middleware example

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export async function middleware(req: NextRequest) {
  const res = await fetch('https://api.humankey.io/api/detect', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      siteKey: process.env.HK_PUBLIC_KEY,
      url: req.url,
      referrer: req.headers.get('referer') ?? undefined,
    }),
  });

  const { action } = await res.json();

  if (action === 'block') {
    return new NextResponse('Too Many Requests', { status: 429 });
  }

  return NextResponse.next();
}

AI Crawler Rules (Block / Monitor / Allow)

Configure per-crawler rules in your Dashboard → Sites → AI Crawler Rules.

Block

Crawler receives "action": "block". Your server-side code should return 429 Too Many Requests.

GPTBotCCBotanthropic-ai

Monitor

Default for all detected crawlers. Logged in your dashboard, traffic passes through.

PerplexityBotApplebot

Allow

Explicitly permitted crawlers. Useful for crawlers you want to index your content.

Googlebotbingbot

HumanKey also generates a custom robots.txt snippet based on your rules. Install it via the WordPress plugin with one click, or copy and paste it manually.

Webhooks

Get real-time notifications when bots are detected. Available on Business and Enterprise plans.

Supported events

  • bot.detected
  • quota.warning
  • quota.exceeded
  • plan.upgraded

Example payload

POST https://your-endpoint.com/webhook
X-HumanKey-Signature: sha256=...

{
  "event": "bot.detected",
  "data": {
    "domain": "yoursite.com",
    "url": "/article/ai-trends-2026",
    "action": "block"
  }
}
// Full payload reference in Dashboard → Integrations.

Signatures use HMAC-SHA256. Verify with your webhook signing secret from Dashboard → Integrations.

Email Notifications

HumanKey sends email notifications about your site's bot traffic. Configure each type independently in Dashboard → Settings → Email Notifications.

Notification types

  • Daily Bot Report — Summary of bot activity from the previous day (all plans)
  • Weekly AI Insights — AI-generated analysis of traffic trends and recommendations (Business+)
  • New Crawler Alerts — Alert when a new AI crawler is first detected on your site (Pro+)
  • Quota Warnings — Alert when monthly verification quota reaches 80%

All notifications are enabled by default. Weekly AI insights use aggregated metrics only — no personal data is processed by AI. Insights are advisory only (EU AI Act compliant).

Detection Methodology & Confidence Scoring

HumanKey uses a proprietary 6-layer detection methodology for high-accuracy classification of every visit.

Detection methodology

  • Layer 1 — Known AI crawler identification (60+ bots classified)
  • Layer 2 — Request metadata analysis
  • Layer 3 — Network origin classification
  • Layer 4 — Visitor interaction analysis
  • Layer 5 — Client environment verification
  • Layer 6 — Proprietary confidence scoring engine combining all layers

All detection runs server-side in the EU. No personal data is used for classification. Results are available in your Dashboard and via the REST API.

Confidence scoring is included on all plans. Detailed analytics data is available on Pro and above.

Bot Farm Detection

HumanKey detects coordinated bot networks using a proprietary multi-stage analysis pipeline. The system identifies patterns of coordinated activity from shared infrastructure.

How it works

  • Collection — Session-level data is collected and processed
  • Analysis — Proprietary algorithm identifies coordinated activity patterns
  • Scoring — Each group receives a danger score
  • Enrichment — Network operator metadata adds infrastructure context

API Endpoints

  • GET /api/behavior/clusters?siteId=X — List detected groups with members and danger scores
  • GET /api/behavior/clusters/:id?siteId=X — Group details with member analysis

Bot farm detection is informational only — no automated blocking. All processing runs on EU infrastructure.

Embeddable Badge

Display an embeddable "HumanKey Verified" badge on your site to show visitors you monitor AI traffic.

<img
  src="https://api.humankey.io/api/badge?siteKey=YOUR_PUBLIC_KEY"
  alt="HumanKey AI Verified"
  width="180"
  height="20"
/>

The badge is an SVG image served with a 1-hour cache. No JavaScript required.

AI Assistant

HumanKey includes a built-in AI Assistant available on every page — both the public website and the dashboard. Click the chat icon in the bottom-right corner to start a conversation.

What you can ask:

  • •Product features, pricing tiers, and plan comparisons
  • •GDPR compliance, data retention, and privacy policies
  • •Integration guides (WordPress plugin, JS snippet, REST API)
  • •Dashboard features, report interpretation, webhook setup
  • •Billing, plan changes, and invoice management

Limitations:

  • •20 messages per conversation (start a new one after)
  • •Conversations are ephemeral — not stored or recoverable
  • •Cannot make binding decisions or access your account data
  • •For complex issues, use the "Talk to a human" link → /contact

AI Act Art. 50 Compliance: The assistant is clearly marked as AI-powered. It provides advisory information only and cannot make automated decisions. A direct link to human support is always available.

Troubleshooting

Installed the snippet but not seeing data? Here are the most common causes and fixes.

1. Content-Security-Policy (CSP) blocking the snippet

Symptom: Browser console shows "Refused to load the script" or the snippet request shows status 0 in DevTools Network tab.

Fix: Add api.humankey.io to both script-src and connect-src in your CSP header:

Content-Security-Policy:
  script-src 'self' https://api.humankey.io;
  connect-src 'self' https://api.humankey.io;

How to check: Open DevTools (F12) → Console → look for "Content Security Policy" or "Refused to load" messages.

2. Ad Blockers (uBlock Origin, Brave Shields, Privacy Badger)

Symptom: detect.js is blocked for some visitors — no verifications counted for them.

Ad blockers may block third-party analytics scripts. This affects only visitors using ad blockers (approximately 15–30% of traffic). AI crawlers and bots — HumanKey's primary detection target — do not use ad blockers, so your bot detection data remains fully accurate. This is expected behavior, not a bug.

3. Cloudflare "Block AI Bots" / "Bot Fight Mode" Most common cause of missing AI data

Symptom: HumanKey shows zero AI bot traffic, even though you know AI crawlers should be visiting your site.

Cause: Cloudflare's "Block AI bots" and "Bot Fight Mode" features block AI crawlers at the network edge, before they reach your website. Since the bots never load your pages, HumanKey's tracking snippet never sees them. This is not a HumanKey bug — the traffic genuinely never arrives.

Fix: In Cloudflare Dashboard → Security → Settings, disable:

  • Block AI bots — set to "Do not block (off)"
  • Bot Fight Mode — toggle off
  • AI Labyrinth — toggle off (can generate misleading traffic data)

Is this safe? Yes. HumanKey monitors and reports AI traffic without blocking it, giving you the data to make informed decisions about which bots to allow or restrict. Disabling Cloudflare's bot blocking does not affect DDoS protection or other security features.

4. Cloudflare Rocket Loader

Symptom: Script never executes. Cloudflare's Rocket Loader modifies async scripts.

Fix: Add data-cfasync="false" to exclude the HumanKey script:

<script data-cfasync="false" src="https://api.humankey.io/api/detect.js?key=YOUR_PUBLIC_KEY" async></script>

5. Cache / CDN Serving Stale HTML

Symptom: Snippet added but dashboard still shows "Not detected" after deploy.

Fix: Purge your CDN or edge cache — Cloudflare: Settings → Caching → Purge Everything. Vercel: Redeploy (auto-purges). Netlify: Deploys → Trigger deploy → Clear cache and deploy.

6. CORS Errors

Symptom: Console shows "Access-Control-Allow-Origin" error on challenge or detect endpoints.

Fix: Verify that the domain registered in your HumanKey dashboard (Dashboard → Sites) matches your actual website URL exactly, including www vs non-www.

6. SPA / Single Page Applications

Symptom: Snippet loads once but doesn't re-fire on route changes.

This is correct behavior. The HumanKey snippet runs once per page load and detects AI crawlers during the initial request. AI crawlers typically don't execute JavaScript or navigate SPA routes, so they're detected on the initial load. No additional configuration needed for React, Vue, or Angular SPAs.

7. I'm seeing data from another account on a shared browser

Symptom: After switching accounts on the same computer, the dashboard briefly shows the previous user's site, time filter, or chat conversation.

Fix: Log out using the avatar menu → Sign Out. HumanKey performs a full client-state purge and hard page reload on logout — any remaining per-user state is cleared and you can sign back in cleanly. If the issue persists, close the tab and reopen it. Each session is fully isolated (GDPR Article 32).

8. "Content Security Policy blocks eval" warnings in the console

Symptom: Visiting a HumanKey-enabled site shows CSP violation warnings mentioning eval in your browser console.

Fix: These warnings are almost always injected by browser extensions (especially crypto wallets and password managers) that run their own scripts on every page. HumanKey enforces a strict Content Security Policy as part of our hardened security posture — our own code never uses eval. To confirm an extension is the source, open the site in an incognito window (extensions are disabled by default in incognito). If the warnings disappear there, a browser extension is the source — not HumanKey.

9. Session recording shows event count but playback area is empty

Symptom: Opening a recording at Dashboard → Recordings displays duration, event count, and file size in the sidebar, but the main playback area is blank.

Fix: This usually means the recording was captured with an older snippet version that did not include full playback data, or the session was still being recorded at the time you opened it. Wait a few minutes and refresh the recording list, then open a newer session. Event counts and durations are stored separately from the playback stream, so older recordings can legitimately show metadata without replayable frames. If a fresh recording still shows an empty playback area, contact Support via /contact with the recording timestamp.

10. "CORB blocked" warnings from HumanKey endpoints

Symptom: Chrome DevTools Issues panel or console shows "CORB blocked" messages referencing HumanKey API endpoints.

Fix: No data is at risk — these are informational browser warnings from a cross-origin security feature, not actual blocks of your tracked data. All HumanKey endpoints receive and process events correctly. Our response handling has been hardened to eliminate these warnings in the latest snippet version. If you continue to see them, hard-refresh your browser (Ctrl+F5 or Cmd+Shift+R) to pick up the current tracker.

Can't find what you need?

Our support team responds within 2 business days.

Contact Support