Zum Hauptinhalt springen

Migration von FriendlyCaptcha

Diese Anleitung hilft Ihnen bei der Migration von FriendlyCaptcha (Proof-of-Work-Widget, oft über friendly-challenge) zu MTCaptcha mit dem Standard-Flow aus mtcaptchaConfig + Widget + CheckToken.

Warum Teams von FriendlyCaptcha migrieren​

  • Bewahren Sie eine privacy-first CAPTCHA-Strategie, während Sie auf die MTCaptcha-Infrastruktur konsolidieren.
  • Wechseln Sie von einer Proof-of-Work-ähnlichen Challenge-Verarbeitung zu den Challenge-Optionen von MTCaptcha.
  • Nutzen Sie MTCaptchas Barrierefreiheit und umfassendere Widget-Anpassungsmöglichkeiten.
  • Sichern Sie eine hochverfügbare globale Abdeckung, einschließlich Festlandchina.

Migrationsüberblick​

FriendlyCaptchaMTCaptcha
Client-ScriptZ. B. https://cdn.jsdelivr.net/npm/friendly-challenge/widget.module.min.js (Modul) oder Bundler-Importhttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Widget-Klasse.frc-captcha (oder Framework-Wrapper um FriendlyCaptcha).mtcaptcha (<div class="mtcaptcha"></div>)
Token-NameMeist frc-captcha-solution (Hidden-Feld / Solution-String)mtcaptcha-verifiedtoken
Backend-APIPOST https://api.friendlycaptcha.com/api/v1/siteverify (hosted) oder Ihr self-hosted Verify-EndpointGET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Nur serverseitig verifizieren

Geben Sie den MTCaptcha-PrivateKey niemals im Frontend aus. Führen Sie CheckToken nur im Backend aus.

Schritt 1: Clientseitiges Script und Widget ersetzen​

<!-- Remove [FriendlyCaptcha] -->
<script type="module" src="https://cdn.jsdelivr.net/npm/friendly-challenge/widget.module.min.js" async defer></script>
<div class="frc-captcha" data-sitekey="YOUR_FRIENDLYCAPTCHA_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

Definieren Sie mtcaptchaConfig mit "sitekey": "YOUR_SITEKEY" vor dem Laden von mtcaptcha.min.js.

Wenn Sie FriendlyCaptcha über JavaScript initialisiert haben (nicht statisches HTML), entfernen Sie dieses Bootstrap und verwenden Sie den MTCaptcha-Anker oder explizites Rendern.

Schritt 2: Serverseitige Verifizierung aktualisieren​

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

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

Verwenden Sie das Formularfeld mtcaptcha-verifiedtoken als token.

Token-Lebensdauer und Einmalverwendung

Validieren Sie Tokens zeitnah. Ein zweiter CheckToken-Aufruf auf denselben Wert kann fehlschlagen. Siehe Token validieren (mit privatem Schlüssel).

Bei eingeschränktem Egress verwenden Sie https://service2.mtcaptcha.com/mtcv1/api/checktoken wie im Guide beschrieben.

Fehlerbehebung​

SymptomWas prüfen
PoW-Widget lädt weiterhinPrüfen, dass FriendlyCaptcha-Module und <div class="frc-captcha"> vollständig entfernt sind.
Falsches Feld im ServerParsing von frc-captcha-solution auf mtcaptcha-verifiedtoken umstellen.
CSP blockierthttps://service.mtcaptcha.com für Script erlauben (und service2 falls benötigt).
Hohe Client-CPU durch altes PoWNach Entfernen von FriendlyCaptcha sollten Nutzer keine PoW-Kosten mehr tragen.
token-expired / invalid-tokenVeralteter Token, Doppelsubmit oder Clock-Skew; Widget aktualisieren und einmal neu senden.

Weitere Informationen​

Post-Migration Checklist​

  • FriendlyCaptcha-Assets und Server-Verify-Endpoints entfernt.
  • mtcaptchaConfig nutzt "sitekey": "YOUR_SITEKEY" vor mtcaptcha.min.js.
  • Backend liest mtcaptcha-verifiedtoken und ruft https://service.mtcaptcha.com/mtcv1/api/checktoken auf.
  • Lade-, Interaktions- und Conversion-Metriken vor/nach der Migration verglichen (PoW vs. MTCaptcha).
  • CSP-/Netzwerkregeln aktualisiert.