Von reCAPTCHA migrieren
Caputchin nutzt dasselbe zweiteilige Modell wie reCAPTCHA, 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 reCAPTCHAs siteverify-Form mit Absicht. 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 reCAPTCHAs Site-Key und Secret-Key.
Das mentale Modell ist unverändert
Alles, was du schon um reCAPTCHA 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
| reCAPTCHA (v2 Checkbox) | Caputchin | |
|---|---|---|
| Skript | <script src="https://www.google.com/recaptcha/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Element | <div class="g-recaptcha" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Token-Feld in einem Formular | g-recaptcha-response (auto-eingefügt) | caputchin-token (auto-eingefügt) |
| Das Token in JS lesen | grecaptcha.getResponse() | das pass-Event detail.token |
Wie reCAPTCHA 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.
| reCAPTCHA | Caputchin | |
|---|---|---|
| Endpunkt | POST https://www.google.com/recaptcha/api/siteverify | POST https://caputchin.com/api/v1/siteverify |
| Anfragefelder | secret, response | secret, response (identisch) |
| Antwort | { success, challenge_ts, hostname, "error-codes" } | { success, challenge_ts, hostname, error-codes, score? } |
| Vertrauensregel | nur handeln, wenn success === true | nur handeln, wenn success === true (identisch) |
In den meisten Stacks ist die einzige Änderung an deinem Verifizierungscode die URL und der Secret-Wert. Die vollständige Anfrage-/Antwort-Referenz, einschließlich der Error-Codes, ist auf ein Token auf deinem Backend verifizieren; Framework-Snippets sind in Backend-Beispielen.
3. Den Score abbilden, falls du reCAPTCHA v3 genutzt hast
reCAPTCHA v3 gibt einen score zurück (0.0 bis 1.0) und bittet dich, eine Schwelle zu wählen, du rätst, wie menschlich eine Anfrage aussah. 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 Wahrscheinlichkeit.
Hatte dein Code if (data.score >= 0.5), ersetz ihn durch if (data.success). Caputchins score-Feld existiert nur für Spiel-Runden und ist die Punktzahl des Spiels (informativ, für deine eigenen Bestenlisten), nie eine Bot-Wahrscheinlichkeit, also gate Zugriff nicht daran.
Was sich beim Wechsel verbessert
- Keine Besucherdaten-Erfassung. reCAPTCHA profiliert deine Besucher; Caputchin erfasst keine IP, keinen User-Agent, keinen Fingerabdruck und keine Verhaltens-Telemetrie, das Protokoll hat nirgendwo, einen Besucher-Identifier abzulegen. Sieh dir die Philosophie an.
- Ein Widget, kein v2-gegen-v3. Es gibt kein separates unsichtbares/Score-Produkt zu wählen; ein Element deckt die Checkbox und das optionale Spiel ab.
- Ein optionales Spiel. Statt eines Ampel-Rasters kannst du die Verifizierung in ein kurzes Spiel verwandeln, das deine Besucher tatsächlich spielen. 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 reCAPTCHA-Disziplin. Liefer das Secret nicht an den Browser. - Das Token ist einmalig. Wie reCAPTCHA verifiziert ein Token einmal. Cache oder spiel es nicht ab.
- Änder den Feldnamen, den dein Backend liest. Das versteckte Feld ist
caputchin-token, nichtg-recaptcha-response, ein häufiger Ein-Zeilen-Fehler.
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.