Migración desde FriendlyCaptcha

Esta guía le ayuda a migrar de FriendlyCaptcha (widget de proof-of-work, normalmente vía friendly-challenge) a MTCaptcha usando el flujo estándar de mtcaptchaConfig + widget + CheckToken.

Por qué los equipos migran de FriendlyCaptcha

• Mantener una estrategia de CAPTCHA "privacy-first" mientras consolida la infraestructura en MTCaptcha.
• Pasar del manejo de desafíos tipo Proof-of-Work a las opciones de desafíos de MTCaptcha.
• Aprovechar el soporte de accesibilidad de MTCaptcha y las opciones ampliadas de personalización del widget.
• Mantener una cobertura global de alta disponibilidad, incluyendo China continental.

Resumen de migración

	FriendlyCaptcha	MTCaptcha
Script cliente	P. ej. https://cdn.jsdelivr.net/npm/friendly-challenge/widget.module.min.js (módulo) o import de bundler	https://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Clase del widget	.frc-captcha (o wrapper de framework sobre FriendlyCaptcha)	.mtcaptcha (<div class="mtcaptcha"></div>)
Nombre del token	Normalmente frc-captcha-solution (campo oculto / string de solución)	mtcaptcha-verifiedtoken
API backend	POST https://api.friendlycaptcha.com/api/v1/siteverify (hosted) o su endpoint self-hosted	GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)

Verificación solo del lado servidor

No exponga su PrivateKey de MTCaptcha en bundles frontend. Ejecute CheckToken solo en el servidor.

Paso 1: Reemplazar el script y el widget del lado cliente

<!-- 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>

Orden de carga

Defina mtcaptchaConfig con "sitekey": "YOUR_SITEKEY" antes de cargar mtcaptcha.min.js.

Si inicializaba FriendlyCaptcha desde JavaScript (no HTML estático), elimine ese bootstrap y use el ancla de MTCaptcha o Renderizado Explícito.

Paso 2: Actualizar la verificación del lado servidor

Reemplace la verificación de FriendlyCaptcha por la API CheckToken de MTCaptcha:

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

Use el campo de formulario mtcaptcha-verifiedtoken como token.

Vida útil del token y uso único

Valide los tokens rápidamente. Una segunda llamada CheckToken para el mismo valor puede fallar. Vea Validar Token (Con Clave Privada).

Solución de problemas

Síntoma	Qué revisar
Aún carga widget PoW	Verifique que imports de FriendlyCaptcha y <div class="frc-captcha"> se eliminaron por completo.
Campo incorrecto en servidor	Reemplace parsing de frc-captcha-solution por mtcaptcha-verifiedtoken.
CSP bloquea	Permita https://service.mtcaptcha.com para script (y service2 si aplica).
CPU alta del cliente por PoW antiguo	Tras retirar FriendlyCaptcha, los usuarios no deberían pagar el coste de proof-of-work.
token-expired / invalid-token	Token obsoleto, doble submit o desfase horario; refresque widget y reintente una vez.

Lecturas adicionales

• MTCaptcha inicio rápido
• Validar Token (Con Clave Privada)
• Cumplimiento de Privacidad y GDPR
• Cumplimiento de Accesibilidad

Post-Migration Checklist

• Assets de FriendlyCaptcha y endpoints de verificación del servidor eliminados.
• mtcaptchaConfig usa "sitekey": "YOUR_SITEKEY" antes de mtcaptcha.min.js.
• Backend lee mtcaptcha-verifiedtoken y llama a https://service.mtcaptcha.com/mtcv1/api/checktoken.
• Métricas de carga, interacción y conversión comparadas antes/después (PoW vs MTCaptcha).
• Reglas CSP/red actualizadas.