Saltar al contenido principal

Migración desde hCaptcha

Esta guía le ayuda a migrar de hCaptcha a MTCaptcha manteniendo el mismo patrón general: cargar un script cliente, renderizar el widget y verificar el token en el servidor.

Por qué los equipos migran de hCaptcha​

  • Mantenga una implementación CAPTCHA orientada a la privacidad mientras estandariza en las operaciones de MTCaptcha.
  • Mejore la accesibilidad con flujos de desafíos e interacción orientados a WCAG.
  • Reduzca la fricción del desafío en viajes de usuario comunes con opciones de baja fricción o validación invisible.
  • Mantenga la fiabilidad del servicio a través de regiones, incluyendo China continental.

Resumen de migración​

hCaptchaMTCaptcha
Script clientehttps://js.hcaptcha.com/1/api.jshttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Clase del widget.h-captcha (contenedor <div class="h-captcha" data-sitekey="…"></div>).mtcaptcha (use <div class="mtcaptcha"></div>)
Nombre del tokenh-captcha-response (campo de formulario o callback)mtcaptcha-verifiedtoken (nombre del input oculto)
API backendPOST https://api.hcaptcha.com/siteverify (secret + response)GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Verificación solo del lado servidor

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

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

<!-- 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>
Orden de carga

Declare mtcaptchaConfig con "sitekey" antes del <script src="...mtcaptcha.min.js"> para que la inicialización lea la clave correcta.

Si usa callbacks de hCaptcha (data-callback, data-expired-callback, etc.), adapte esa lógica a APIs JS o callbacks de estado de MTCaptcha. Vea JavaScript Callbacks.

Paso 2: Actualizar la verificación del lado del servidor​

Reemplace la verificación de hCaptcha por:

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

Use el valor enviado de mtcaptcha-verifiedtoken como token.

Vida útil del token y uso único

Los tokens expiran rápidamente y normalmente son de un solo uso en CheckToken. Vea Validar Token (Con Clave Privada).

Solución de problemas​

SíntomaQué revisar
Falta widgetConfiguración de dominio/sitio en Admin Portal; eliminar markup residual de hCaptcha.
CSP bloquea scriptPermitir https://service.mtcaptcha.com (y service2 si usa cargador secundario).
Manejo obsoleto de h-captcha-responseActualizar parser backend y pruebas a mtcaptcha-verifiedtoken.
token-expiredEl usuario tardó demasiado; refrescar widget y reenviar.
token-duplicate-cal / reuseNo llamar CheckToken dos veces para el mismo token salvo política explícita.
Callback no ejecutaRe-mapear callbacks de hCaptcha a equivalentes de MTCaptcha (JS Callbacks).

Lecturas adicionales​

Post-Migration Checklist​

  • Se eliminaron script hCaptcha y manejo de h-captcha-response de extremo a extremo.
  • mtcaptchaConfig usa "sitekey": "YOUR_SITEKEY" antes de cargar mtcaptcha.min.js.
  • Backend verifica mtcaptcha-verifiedtoken vía https://service.mtcaptcha.com/mtcv1/api/checktoken.
  • Flujos callback/async actualizados y con regresión probada.
  • Se probaron rutas de envío válido, token inválido y token duplicado.
  • CSP y firewall actualizados para script/API de MTCaptcha.