Von hCaptcha migrieren
Caputchin nutzt dasselbe zweiteilige Modell wie hCaptcha, ein Widget auf der Seite, das ein Token produziert, und eine serverseitige Prüfung, die es bestätigt, also ist das Migrieren meist ein mechanischer Tausch, kein Neuschreiben. Der Server-Austausch spiegelt insbesondere die siteverify-Form, der hCaptcha selbst folgt. Diese Anleitung gibt das Vorher-und-Nachher für jedes Stück.
Hast du noch kein Caputchin-Konto und keinen Site-Key erstellt, mach zuerst dein Konto erstellen; du brauchst einen Public Key (cpt_pub_...) für die Seite und ein Secret (cpt_sec_...) für dein Backend, dieselbe Aufteilung wie hCaptchas Site-Key und Secret-Key.
Das mentale Modell ist unverändert
Alles, was du schon um hCaptcha gebaut hast, ein Widget rendern, ein Token sammeln, es an deinen Server POSTen, es verifizieren, bevor du der Anfrage traust, bleibt. Nur die Namen und Endpunkte ändern sich.
1. Den Client-Snippet tauschen
| hCaptcha | Caputchin | |
|---|---|---|
| Skript | <script src="https://js.hcaptcha.com/1/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Element | <div class="h-captcha" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Token-Feld in einem Formular | h-captcha-response (auto-eingefügt) | caputchin-token (auto-eingefügt) |
| Das Token in JS lesen | hcaptcha.getResponse() | das pass-Event detail.token |
Wie hCaptcha fügt das Caputchin-Widget ein verstecktes Token-Feld automatisch ein in das Formular, in dem es sitzt, sodass du, wenn dein Formular schon einen normalen POST machte, nur das Element und den Feldnamen änderst, den dein Backend liest. Sieh dir das Widget hinzufügen für die vollständige Client-Einrichtung und die CDN-vs-npm-Wahl an.
2. Die Server-Verifizierung tauschen
Hier sind die zwei am nächsten, die Anfrage- und Antwortformen reihen sich fast Feld für Feld auf.
| hCaptcha | Caputchin | |
|---|---|---|
| Endpunkt | POST https://api.hcaptcha.com/siteverify | POST https://caputchin.com/api/v1/siteverify |
| Anfragefelder | secret, response | secret, response (identisch) |
| Antwort | { success, challenge_ts, hostname, "error-codes", score? } | { success, challenge_ts, hostname, error-codes, score? } |
| Vertrauensregel | nur handeln, wenn success === true | nur handeln, wenn success === true (identisch) |
Ein Format-Hinweis: hCaptchas Verifizierungs-Endpunkt erwartet application/x-www-form-urlencoded, während Caputchins JSON akzeptiert. Sendete dein bestehender Code form-kodierte Felder, wechsel den Body auf JSON ({"secret":"...","response":"..."}) mit Content-Type: application/json. Die Felder selbst sind unverändert. Die vollständige Anfrage-/Antwort-Referenz ist auf ein Token auf deinem Backend verifizieren; Framework-Snippets sind in Backend-Beispielen.
3. Den Score fallen lassen, falls du hCaptcha Enterprise genutzt hast
hCaptcha Enterprise gibt einen Risiko-score zurück (wo eine höhere Zahl mehr Risiko bedeutet) und bittet dich, eine Schwelle zu wählen. Caputchin funktioniert nicht so: success ist ein maßgebliches Bestanden/Nicht, weil die Verifizierung tatsächlich gelöst wurde (eine Proof-of-Work-Prüfung oder eine auf dem Server neu abgeleitete Spiel-Runde), keine Risiko-Schätzung.
Hatte dein Code if (data.score < 0.7), ersetz ihn durch if (data.success). Caputchins score-Feld ist unverwandt: es existiert nur für Spiel-Runden und ist die Punktzahl des Spiels (informativ, für deine eigenen Bestenlisten), nie ein Risiko oder eine Bot-Wahrscheinlichkeit, also gate Zugriff nicht daran. (Beachte, die Richtung ist auch entgegengesetzt, hCaptchas Score steigt mit dem Risiko; Caputchins steigt mit der Spiel-Leistung.)
Was übernommen wird und was sich verbessert
- Die Datenschutz-Haltung, für die du hCaptcha gewählt hast, bleibt. Caputchin erfasst keine IP, keinen User-Agent, keinen Fingerabdruck und keine Verhaltens-Telemetrie; das Protokoll hat nirgendwo, einen Besucher-Identifier abzulegen, also gibt es keinen zu leaken oder zu verkaufen. Sieh dir die Philosophie an.
- Ein optionales Spiel. Statt einer Bild-Auswahl-Aufgabe kannst du die Verifizierung in ein kurzes Spiel verwandeln, das deine Besucher tatsächlich spielen, und es ist der Teil, der gegen KI-Löser standhält. Sieh dir ein Spiel hinzufügen an.
- Eine strikte CSP bleibt strikt. Caputchin läuft unter einer engen Content-Security-Policy; du erlaubst ein paar Origins, statt deine Policy zu lockern. Sieh dir wie Caputchin Spiele sandboxt an.
Stolperfallen
- Zwei Keys, zwei Heimaten. Der Public Key (
cpt_pub_...) kommt auf die Seite; das Secret (cpt_sec_...) bleibt nur serverseitig, genau die hCaptcha-Disziplin. Liefer das Secret nicht an den Browser. - Das Token ist einmalig. Wie hCaptcha verifiziert ein Token einmal. Cache oder spiel es nicht ab.
- Änder den Feldnamen, den dein Backend liest. Das versteckte Feld ist
caputchin-token, nichth-captcha-response, ein häufiger Ein-Zeilen-Fehler. - Body-Format. Sende die Verifizierungs-Anfrage als JSON, nicht form-kodiert.
Siehe auch
- Das Widget hinzufügen: die vollständige Client-Einrichtung.
- Ein Token auf deinem Backend verifizieren: die maßgebliche
siteverify-Referenz. - Backend-Beispiele: der Verifizierungs-Aufruf in jeder Sprache.
- Ein Spiel hinzufügen: die Verifizierung in ein Spiel verwandeln.