Zum Hauptinhalt springen

Migration von hCaptcha

Diese Anleitung hilft Ihnen bei der Migration von hCaptcha zu MTCaptcha bei gleichbleibendem Grundmuster: Client-Script laden, Widget rendern und anschließend Token serverseitig verifizieren.

Warum Teams von hCaptcha migrieren​

  • Bewahren Sie eine datenschutzorientierte CAPTCHA-Implementierung und standardisieren Sie gleichzeitig auf die MTCaptcha-Operations.
  • Verbessern Sie die Barrierefreiheit mit WCAG-orientierten Challenge- und Interaktionsflüssen.
  • Reduzieren Sie Challenge-Reibung in typischen Nutzerreisen durch Optionen mit geringer Reibung/unsichtbarer Validierung.
  • Stellen Sie die Zuverlässigkeit des Dienstes über Regionen hinweg sicher, einschließlich Festlandchina.

Migrationsüberblick​

hCaptchaMTCaptcha
Client-Scripthttps://js.hcaptcha.com/1/api.jshttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Widget-Klasse.h-captcha (Container <div class="h-captcha" data-sitekey="…"></div>).mtcaptcha (verwenden Sie <div class="mtcaptcha"></div>)
Token-Nameh-captcha-response (Formularfeld oder Callback)mtcaptcha-verifiedtoken (Name des Hidden-Inputs)
Backend-APIPOST https://api.hcaptcha.com/siteverify (secret + response)GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Nur serverseitig verifizieren

Führen Sie CheckToken nur auf dem Server aus. Geben Sie den MTCaptcha-PrivateKey niemals an den Browser weiter.

Schritt 1: Clientseitiges Script und Widget ersetzen​

<!-- Remove [hCaptcha] -->
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
<div class="h-captcha" data-sitekey="YOUR_HCAPTCHA_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

Deklarieren Sie mtcaptchaConfig mit "sitekey" vor dem <script src="...mtcaptcha.min.js">, damit der SiteKey bei der Initialisierung verfügbar ist.

Wenn Sie hCaptcha-Callbacks (data-callback, data-expired-callback usw.) verwendet haben, bilden Sie diese Logik auf MTCaptcha JS APIs oder Status-Callbacks ab. Siehe JavaScript-Rückrufe.

Schritt 2: Serverseitige Verifizierung aktualisieren​

Ersetzen Sie die hCaptcha-Verifizierung durch:

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

Verwenden Sie den gesendeten Wert mtcaptcha-verifiedtoken als token.

Token-Lebensdauer und Einmalverwendung

Tokens laufen schnell ab und sind unter Standardbedingungen einmal für CheckToken nutzbar. Siehe Token validieren (mit privatem Schlüssel).

Für strikte Egress-Vorgaben verwenden Sie https://service2.mtcaptcha.com/mtcv1/api/checktoken und die in Validate Token dokumentierte IP-Liste.

Fehlerbehebung​

SymptomWas prüfen
Widget fehltDomain-/Site-Einstellungen im Admin Portal; verbliebene hCaptcha-Markup-Reste entfernen.
CSP blockiert Scripthttps://service.mtcaptcha.com erlauben (und service2, wenn der sekundäre Loader aus Quick Start genutzt wird).
Veraltete h-captcha-response VerarbeitungAlle Server-Parser und Tests auf mtcaptcha-verifiedtoken umstellen.
token-expiredNutzer hat zu lange gewartet; Widget aktualisieren und neu senden.
token-duplicate-cal / WiederverwendungCheckToken nicht zweimal für denselben Token aufrufen, außer bewusst konfiguriert.
Callback läuft niehCaptcha-Callbacks auf MTCaptcha-Äquivalente umstellen (JS Callbacks).

Weitere Informationen​

Post-Migration Checklist​

  • hCaptcha-Script und h-captcha-response Handling vollständig entfernt.
  • mtcaptchaConfig nutzt "sitekey": "YOUR_SITEKEY" vor dem Laden von mtcaptcha.min.js.
  • Backend verifiziert mtcaptcha-verifiedtoken über https://service.mtcaptcha.com/mtcv1/api/checktoken.
  • Callback-/Async-Flows aktualisiert und regressionsgetestet.
  • Gültiger Submit, ungültiger Token und Duplicate-Check-Pfade getestet.
  • CSP- und Firewall-Regeln für MTCaptcha-Script und API aktualisiert.