Skip to main content
HumanKey
Wersja polska →

Documentation

Integration guides for WordPress, JavaScript, and webhooks — with a REST API coming soon.

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 APIComing soon→AI Crawler RulesAfter setup

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

WordPress Plugin

A dedicated HumanKey WordPress plugin is coming soon to the official WordPress.org directory. Until then, you can add HumanKey to any WordPress site in about a minute with the 1-line JS snippet below — no plugin required.

  1. 1Copy your Site Public Key from your Dashboard → Sites
  2. 2Copy the HumanKey snippet from the 1-Line JS Install section below
  3. 3Paste it into your site header — using your theme's header settings or a headers & footers helper plugin
  4. 4Save — the tracking snippet is now live on all pages

What the WordPress plugin will add (coming soon)

  • • 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,
        },
      ],
    },
  },
});

Legal note for the site operator

The snippet reads information from your visitors’ terminal equipment. Under Art. 5(3) of Directive 2002/58/EC — in Poland, art. 399 of the Prawo komunikacji elektronicznej — that access requires the visitor’s prior consent unless it is strictly necessary to provide the service the visitor has requested. The obligation to obtain that consent, and to give the information required by Art. 13 GDPR, rests on you as the controller in respect of your own website. Whether an exemption applies to your deployment depends on how and for what purposes you deploy the snippet, which are matters within your knowledge.

HumanKey does not detect, collect, evaluate or enforce visitor consent, does not render, host or operate any consent interface on your site, and does not assess whether your deployment satisfies any legal requirement. The snippet executes whenever it is loaded.

On humankey.io the snippet is rendered conditionally: our own page component checks our analytics-consent state and returns no script element when consent is absent, so the script is never loaded. This describes how our own website is built. It is not an integration pattern supplied, approved, supported or warranted by HumanKey.

REST API (Server-Side)

A server-side REST integration — calling HumanKey from Next.js middleware, Laravel, Django, or any backend — is coming soon, together with our ingest API.

Today, the fastest way to add HumanKey to any platform is the one-line JavaScript snippet shown above: it runs on any site that allows a script tag and needs no server-side code.

Want to be notified when the server-side REST API ships? Reach out via the contact page.

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, including a machine-readable Content Signals rights declaration (an advisory standard that tells AI your content is findable and citeable, but not for training without a license). Copy and paste it into your site manually.

AI Readiness Score

The AI Readiness Score (Dashboard → AI Magnet → Overview) rates how easily AI systems can understand your site, from 0 to 100.

Once you have verified a site, HumanKey fetches your homepage and analyses its structured data, metadata, headings, images and content depth alongside your crawler configuration. An unverified or unreachable site gets a configuration-only score.

How to read it: the 0–100 headline score is shown on every plan. The detailed per-category breakdown — with links to the exact setting that improves each area — is available on the Pro plan and above; Free plans see how many issues were found.

The score is advisory guidance based on what HumanKey can read from your page — not a ranking or visibility guarantee. Improving it does not promise AI citations or search placement.

Structured Data (JSON-LD)

HumanKey can generate schema.org markup (JSON-LD) — a machine-readable description of a page that helps AI systems and search engines parse what your content is about. Generate it in Dashboard → AI Magnet → robots.txt and llms.txt (Pro plan and above).

1. Generate

Choose WebSite or FAQ, fill in the fields, and generate the JSON-LD snippet.

2. Copy onto your page

Paste the generated JSON-LD script block into the head section of the matching page on your own site.

3. Match visible content

The markup must describe content that is actually visible on that page — never add schema for content users cannot see.

4. Validate

Check the markup with the schema.org validator (validator.schema.org) before you publish.

Structured data is advisory context, not a ranking or visibility lever. It does not guarantee AI citations or search placement, and Google retired FAQ rich results in 2026 — so treat it as machine-readable context, not a rich-result badge.

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%, and again when it is fully used (100%)

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 privacy-preserving multi-signal classification pipeline. Every visit is evaluated against three category groups before a confidence-graded verdict is issued.

Signal categories

  • Crawler & request signals — known AI crawler taxonomy (75+ bots) + structured request metadata
  • Behavior & environment signals — interaction quality + browser environment consistency
  • Confidence engine — combined assessment with admin-reviewable advisory output (GDPR Art. 22 safeguard)

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

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

Bot Farm Detection

HumanKey identifies coordinated bot networks via privacy-preserving traffic analysis. Detected groups appear in the dashboard with confidence-graded danger ratings and network operator context (sourced via public registries).

Detected bot networks appear in your dashboard's Behavior section.

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

Trust Badges

HumanKey offers two embeddable badges. They are different products — pick the one that matches your plan and goal.

1. Certified Human Traffic Badge (all plans, including Free)

A live status widget — a small floating pill that reflects your site's last-24h human-vs-bot traffic. Add this one-line script (it carries your public key); it appears automatically, with no configuration.

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

Get it in Dashboard → AI Magnet → Badges (copy the snippet). Available on every plan, including Free.

2. Embeddable Verified Badge (Pro plan and above)

A static SVG trust mark showing your verified domain, with a public click-through verification page. Enable and theme it in Dashboard → AI Magnet → Badges, then embed:

<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. Free plans see a generic (non-domain) badge until they upgrade.

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.

7. 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.

8. 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).

9. "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.

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