Migration von reCAPTCHA

Diese Anleitung hilft Ihnen bei der Migration von Google reCAPTCHA (v2 Checkbox/Invisible oder v3) zu MTCaptcha mit parallelen Anpassungen im Browser und auf Ihrem Server.

Warum Teams von reCAPTCHA migrieren

• Verwenden Sie einen Anbieter, der auf CAPTCHA-spezifischen Missbrauchsschutz und datenschutzorientierte Datenverarbeitung fokussiert.
• Verbessern Sie die Barrierefreiheit für Nutzer, die mit häufigen Challenge-Flows mit reinen Bild-Challenges Schwierigkeiten haben.
• Halten Sie die Verfügbarkeit für globale Zielgruppen auf einem zuverlässigen Niveau, einschließlich Festlandchina.
• Behalten Sie ein vertrautes Integrationsmodell bei: Script laden, Widget rendern, Token serverseitig verifizieren.

Migrationsüberblick

	reCAPTCHA	MTCaptcha
Client-Script	https://www.google.com/recaptcha/api.js	https://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Widget-Klasse	.g-recaptcha (v2-Widget-Container; v3 lädt ein Script ohne sichtbares Widget)	.mtcaptcha (verwenden Sie <div class="mtcaptcha"></div>)
Token-Name	g-recaptcha-response (Formularfeld oder Callback)	mtcaptcha-verifiedtoken (Name des Hidden-Inputs)
Backend-API	POST https://www.google.com/recaptcha/api/siteverify (secret + response)	GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)

Nur serverseitig verifizieren

Rufen Sie MTCaptcha CheckToken nur im Backend auf. Binden Sie Ihren PrivateKey niemals im Frontend ein und geben Sie ihn nicht an den Browser weiter.

Schritt 1: Clientseitiges Script und Widget ersetzen

<!-- Remove [reCAPTCHA] -->
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<div class="g-recaptcha" data-sitekey="YOUR_RECAPTCHA_SITE_KEY"></div>

<!-- Add [MTCaptcha] -->
<script>
  var mtcaptchaConfig = { "sitekey": "YOUR_SITEKEY" };
</script>
<script src="https://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js" async defer></script>
<div class="mtcaptcha"></div>

Lade-Reihenfolge

Setzen Sie var mtcaptchaConfig = { "sitekey": "YOUR_SITEKEY" }; vor dem Laden von mtcaptcha.min.js, damit der Client den SiteKey beim Initialisieren liest.

Wenn Sie reCAPTCHA v3 (nur Score, kein sichtbares Widget) verwendet haben, entfernen Sie das v3-Script und alle execute-Aufrufe; fügen Sie den MTCaptcha-Anker <div class="mtcaptcha"></div> hinzu (oder verwenden Sie Explicit Render, falls Sie das Rendering bereits anpassen).

Schritt 2: Serverseitige Verifizierung aktualisieren

Ersetzen Sie die reCAPTCHA-Verifizierung durch die MTCaptcha CheckToken API:

GET https://service.mtcaptcha.com/mtcv1/api/checktoken?privatekey=YOUR_PRIVATEKEY&token=VERIFIED_TOKEN

Lesen Sie VERIFIED_TOKEN aus dem übermittelten Formularfeld mtcaptcha-verifiedtoken (nicht g-recaptcha-response).

Token-Lebensdauer und Einmalverwendung

Verifizierte Tokens sind kurzlebig. Validieren Sie direkt nach dem Formular-Submit und rechnen Sie mit einer erfolgreichen CheckToken-Prüfung pro Token; ein zweiter Check kann mit einem Duplicate-Token-Fehler fehlschlagen. Siehe Token validieren (mit privatem Schlüssel).

Wenn Ihre Infrastruktur feste ausgehende IPs benötigt, verwenden Sie https://service2.mtcaptcha.com/mtcv1/api/checktoken und die dokumentierte Allowlist im selben Guide.

Fehlerbehebung

Symptom	Was prüfen
Widget erscheint nicht	Domain-Allowlist und Site-Konfiguration im MTCaptcha Admin Portal; Browser-Konsole auf Script-Fehler prüfen.
Script durch CSP blockiert	https://service.mtcaptcha.com erlauben (und https://service2.mtcaptcha.com, falls Sie den sekundären Client laut Quick Start laden).
invalid-token / token-expired	Aktuellstes mtcaptcha-verifiedtoken senden; kein Caching alter POST-Bodies und keine Doppelsubmits ohne Widget-Refresh.
privatekey-mismatch-token	SiteKey und PrivateKey müssen zur gleichen MTCaptcha-Site gehören.
CheckToken schlägt serverseitig fehl	Ausgehenden Traffic prüfen; service2-Host und IP-Allowlist aus Validate Token testen.

Weitere Informationen

• MTCaptcha Schnellstart
• Token validieren (mit privatem Schlüssel)
• Datenschutz & GDPR-Compliance
• Barrierefreiheits-Compliance

Post-Migration Checklist

• Alle reCAPTCHA-Script-Tags und serverseitigen siteverify-Codepfade entfernt.
• mtcaptchaConfig mit "sitekey": "YOUR_SITEKEY" ist vor mtcaptcha.min.js definiert.
• Formular-POST enthält mtcaptcha-verifiedtoken und das Backend liest nur dieses Feld.
• Backend ruft https://service.mtcaptcha.com/mtcv1/api/checktoken (oder service2 laut Richtlinie) auf und akzeptiert nur success: true.
• Gültiger Submit, Expired-Token-Pfad und falsche/fehlende Token-Ablehnung getestet.
• Produktions- und Dev-Hostnamen stimmen mit den Domain-Einstellungen im Admin Portal überein.
• CSP/Netzwerk erlauben MTCaptcha-Script- und API-Hosts.