Doku
In drei Schritten eingebaut, ohne Konto und ohne Schlüssel. Zum Ausprobieren gibt es die Live-Demo.
1. Einbauen
Skript laden und <div class="human-check"> ins Formular setzen. Beim Absenden prüft das Widget den Besucher und legt das Feld humancheck-token ins Formular.
<script src="https://placeforhumans.org/humancheck.js" defer></script>
<form action="/login" method="post">
<input name="email"> <input name="passwort" type="password">
<div class="human-check" data-use="login"></div>
<button type="submit">Anmelden</button>
</form>data-use sagt, wofür geprüft wird (siehe unten), und bestimmt die Empfehlung. Optional: data-theme="light" oder "dark" für feste Farben (sonst folgt das Widget dem Gerät des Besuchers), data-callback="meineFunktion" für eine Funktion, die nach der Prüfung das Ergebnis bekommt.
Textmodus für Kommentare, Bewertungen und Nachrichten
Mit data-mode="text" prüft Human Check zusätzlich, ob der Text im genannten Feld selbst getippt wurde: Rhythmus, Tempo, Korrekturen, Einfügen. Zu uns geht dabei nur die Länge des Texts, nie sein Inhalt. Ohne data-field nimmt das Widget das erste textarea im Formular.
<div class="human-check" data-mode="text" data-field="nachricht"></div>2. Auf deinem Server prüfen
Schick das Token an die Prüfstelle, am besten mit use: Dann zählt dein Zweck, nicht der aus dem Browser. Das Token gilt 5 Minuten und nur ein einziges Mal. Vergleich immer den hostname mit deiner Domain, sonst könnte jemand ein Token einer anderen Seite unterschieben.
Node.js
const res = await fetch("https://placeforhumans.org/api/v1/verify", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ token: req.body["humancheck-token"], use: "login" }),
});
const check = await res.json();
if (!check.success || check.hostname !== "deine-seite.de") {
return res.status(403).send("Ungültige Prüfung.");
}
const { action, stepUp, hint } = check.recommendation;
if (action === "block") return res.status(403).send(hint);
if (action === "step-up") return sendeCodePerEmail(); // stepUp sagt, was passt
// "allow": weiter wie gewohntPHP
$res = file_get_contents("https://placeforhumans.org/api/v1/verify", false,
stream_context_create(["http" => [
"method" => "POST",
"header" => "Content-Type: application/x-www-form-urlencoded",
"content" => http_build_query(["token" => $_POST["humancheck-token"] ?? "", "use" => "login"]),
]]));
$check = json_decode($res, true);
if (empty($check["success"]) || $check["hostname"] !== "deine-seite.de"
|| $check["recommendation"]["action"] === "block") {
http_response_code(403);
exit($check["recommendation"]["hint"] ?? "Ungültige Prüfung.");
}curl
curl -X POST https://placeforhumans.org/api/v1/verify \
-d "token=DAS_TOKEN_AUS_DEM_FORMULAR" -d "use=login"3. Die Antwort
human ist unsere Empfehlung ab einem Mensch-Wert von 70. Du kannst auch selbst mit score (0–100) entscheiden. verdict fasst zusammen (mensch, unsicher, bot, ausgeschlossen), layers zeigt die Punkte der fünf Prüfschichten, und jeder Befund in reasons hat einen festen code für eigene Regeln. confidence (hoch, mittel, gering) und coverage sagen, wie viele der 100 Punkte gemessen statt angenommen sind: Ein Login-Formular liefert wenig Messdaten, ein getippter Text viele. Bei einem Fehler kommt success: false mit token-missing, token-invalid, token-expired oder token-used.
{
"success": true,
"human": true,
"score": 95,
"verdict": "mensch",
"confidence": "hoch",
"coverage": 100,
"recommendation": {
"use": "comment",
"action": "allow",
"reason": "Mensch-Wert 95 (mensch, Aussagekraft hoch).",
"stepUp": null,
"hint": null
},
"hostname": "deine-seite.de",
"checkedAt": "2026-11-21T12:30:00.000Z",
"layers": { "input": 35, "browser": 20, "network": 20, "pow": 10, "extra": 10 },
"reasons": [
{ "layer": "input", "code": "input.motion_bell", "text": "Zielbewegung beschleunigt und bremst weich (Übereinstimmung 0,81)", "points": 10, "good": true },
{ "layer": "input", "code": "input.motion_fitts", "text": "Zielzeit passt zum Fitts-Gesetz (164 ms pro Bit)", "points": 5, "good": true },
{ "layer": "input", "code": "input.rhythm", "text": "Natürlicher, unregelmäßiger Anschlagrhythmus", "points": 5, "good": true },
{ "layer": "browser", "code": "browser.clean", "text": "Echter Browser ohne Automatisierungsspuren", "points": 0, "good": true }
],
"checkId": "q3Xc…",
"feedbackKey": "Hk2…"
}Was gemessen wird
- Bewegung (bis 25 Punkte), bei jedem Besuch: am Computer Glockenform der Zielbewegung, Abbremsen in Kurven (Zwei-Drittel-Gesetz), Fitts-Gesetz und Feinkorrektur; am Handy Dauer und Rollen des Fingers, Streuung der Treffpunkte, Fitts zwischen Tipps und Daumen-Bogen beim Wischen.
- Eingabe (bis 15), nur wenn getippt wird: Rhythmus, Zeitverteilung und Handwechsel. Passwortfelder werden nie Zeichen für Zeichen ausgewertet.
- Zeitbeweis: Der Server misst selbst, wie lange jemand im Formular war. Gemeldete Tippdaten, die nicht zu dieser Uhr passen, sind gefälscht.
- KI-Köder: ein unsichtbarer Hinweis im Formular, dem nur ein KI-Agent folgt. Menschen und Screenreader sehen ihn nicht. Abschalten mit
data-bait="off". - Fehlende Bewegung kostet nie Punkte, nur eindeutig programmierte Spuren.
Empfehlung je Einsatzzweck
recommendation.action ist allow (durchlassen), step-up (Zusatzschritt) oder block (ablehnen), mit Begründung in reason und einem Hinweis für den Besucher in hint. Eindeutige Automatisierung wird immer abgelehnt. Unsichere Fälle bekommen einen Zusatzschritt statt einer Sackgasse. Beim Login und Bezahlen wird nie wegen des Werts gesperrt, weil ein Fehlurteil dort echte Kunden aussperrt.
| use | Zusatzschritt bei step-up |
|---|---|
login | Zweiten Faktor oder Code per E-Mail verlangen |
signup | E-Mail-Adresse bestätigen lassen, bevor das Konto aktiv wird |
comment | Zur Freigabe zurückhalten |
contact | Annehmen, aber als möglichen Spam markieren |
checkout | Zusätzliche Zahlungsbestätigung verlangen (3-D Secure) |
form | Zusätzlich bestätigen lassen, z. B. per E-Mail |
4. Rückmeldung: War es Spam?
Mit checkId und feedbackKey aus der Antwort kannst du später melden, ob es Spam war ("spam") oder echt ("legit"). Den Schlüssel bekommt nur, wer das Token einlöst, also nur du. Aus diesen Rückmeldungen entstehen die öffentlichen Fehlerraten.
await fetch("https://placeforhumans.org/api/v1/feedback", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ checkId: check.checkId, feedbackKey: check.feedbackKey, outcome: "spam" }),
});Seiten mit JavaScript (fetch, React, Vue …)
Wer per JavaScript absendet, holt das Token selbst ab und schickt es mit:
const { token } = await humanCheck.getToken(); // optional: "#mein-widget"
await fetch("/api/kontakt", { method: "POST", body: JSON.stringify({ text, token }) });Hilfe für Besucher
- Seite neu laden und noch einmal absenden.
- VPN oder Proxy ausschalten.
- Browser-Erweiterungen, die Skripte blockieren, für diese Seite erlauben.
- Einen aktuellen Browser verwenden.
Grenzen und Fairness
- Gespeichert werden nur Zählwerte (Tipp-Tempo, Klicks …) und das Ergebnis, ohne IP-Adresse und ohne Inhalte deiner Formulare. Nach 90 Tagen wird alles gelöscht.
- Pro Anschluss gehen bis zu 100 Prüfungen pro Stunde, damit der Dienst kostenlos bleiben kann.
- Ohne Bestätigung durch die unsichtbare Zusatzprüfung ist ein Ergebnis höchstens
unsicher: Alles, was ein Browser meldet, lässt sich fälschen. - Der Textmodus erkennt, ob getippt wurde, nicht wer den Text verfasst hat. Wer einen fremden Text abtippt, fällt nicht auf.
- Besucher aus Rechenzentren und VPNs bekommen einen niedrigeren Wert. Entscheide mit
score, wie streng du sein willst. - Kostenlos und ohne Gewähr. Kein System erkennt Bots mit absoluter Sicherheit.