Web SDK de Prevención de fraude

El Web SDK de Prevención de fraude se ejecuta en tu página — una landing page, una pantalla de registro o inicio de sesión, o cualquier recurso protegido. Solicita un veredicto para la visita actual y se lo devuelve a tu código, para que puedas decidir qué hacer con el tráfico — registrarlo, marcarlo o pedir al visitante una verificación adicional.

Inicio rápido

<!-- Load the Fraud Prevention SDK -->
<script src="https://cdn.captcha-cdn.net/bot-signal.js"></script>

<script>
  BotSignal.init({
    appKey: 'YOUR_APP_KEY',
    onVerdict: function (verdict) {
      // verdict.is_bot, verdict.score, verdict.action — see Verdict Reference
      if (verdict.is_bot) {
        // exclude this visit from your funnel / suppress conversions
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>

BotSignal.init() también devuelve una Promise<BotVerdict>, así que también puedes usar await en lugar de onVerdict — ambos reciben el mismo objeto de veredicto.

const verdict = await BotSignal.init({ appKey: 'YOUR_APP_KEY' });

Opciones

option	type	default	Descripción
appKey	string	—	Obligatorio. Tu clave de aplicación de Prevención de fraude.
domain	string	signal-v1.world-dynamic.com	Dominio de señales al que el SDK envía las solicitudes.
tokenParam	string	_ctk	Parámetro de consulta de la URL del que el SDK lee el token de clic.
onVerdict	(v) => void	—	Se invoca una vez con el veredicto final. El principal punto de integración. init() también devuelve Promise<BotVerdict>.
onError	(err) => void	—	Se invoca ante cualquier fallo. El SDK nunca lanza excepciones hacia tu página.
onChallenge	(v) => creds | null | Promise<…>	—	Sobrescribe las credenciales de escalado: devuelve tus propias { appKey, serverToken } (serverToken emitido por tu backend), o null para omitir el escalado. Si no se define, se usan las credenciales por defecto emitidas por el backend en verdict.escalate (sin configuración).
challengeConfig	object	—	Apariencia/ubicación del captcha: product (popup/float/embed), container, theme, lang.
onEscalate	(displayType) => void	—	Se invoca cuando se muestra un captcha de escalado.
onEscalateDone	(passed, detail) => void	—	Se invoca tras el escalado. passed = el visitante lo superó; detail = { token, challengeId, cid } para la verificación del lado del servidor del paso.

El escalado lo decide el servidor. El SDK muestra un captcha únicamente cuando el action del veredicto del servidor es challenge y la aplicación está configurada con una acción de escalado correspondiente — no existe un interruptor del lado del cliente para ello. Usa onChallenge para proporcionar tus propias credenciales o para omitir el escalado, y challengeConfig para controlar su apariencia. Después de que un visitante lo supere, verifica el resultado en tu propio backend con detail.token (más challenge_id/cid) — no confíes únicamente en el indicador passed del lado del cliente.

Escenarios con fuente de tráfico

Si un tercero te entrega visitantes y ambas partes necesitan conciliar sobre una conclusión por clic, el SDK también puede leer un token de clic de la URL de la página. Eso es específico de los flujos de tráfico de pago — consulta la guía de Fraude publicitario.

Uso del veredicto

onVerdict recibe un objeto BotVerdict. Los dos campos que más usarás:

• verdict.is_bot — true cuando la visita se juzga como automatizada/inválida.
• verdict.action — lo que te recomendamos hacer: record_only, challenge o flag.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // normal-looking traffic — proceed, just log the verdict
        break;
      case 'flag':
        // suspicious — keep serving the page but mark this visit as low quality
        markLowQuality(verdict);
        break;
      case 'challenge':
        // high risk — handled by escalation if enabled (see below)
        break;
    }
  },
});

Consulta la lista completa de campos y el manejo recomendado en la Referencia del veredicto.

Escalado

Cuando una visita parece de alto riesgo, Prevención de fraude puede pedir al visitante que complete una verificación adicional antes de tratarlo como un usuario real. Esto lo decide el veredicto del servidor, no un indicador del lado del cliente — se ejecuta siempre que el action del veredicto es challenge y la aplicación tiene configurada una acción de escalado.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // se está mostrando una verificación adicional al visitante
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // el visitante superó la verificación adicional — verifica detail.token en tu backend
    } else {
      // no la superó — conserva la recomendación del veredicto original
    }
  },
  onVerdict: function (verdict) {
    // si el visitante superó el escalado, verdict.is_bot se actualiza a false
  },
});

Notas:

• El escalado solo se activa cuando el action del veredicto es challenge. Para todas las demás visitas no se muestra nada y la experiencia del visitante no se ve afectada.
• Por defecto el SDK usa las credenciales emitidas por el backend en verdict.escalate (sin configuración). Usa onChallenge para proporcionar tus propias { appKey, serverToken } o para omitir el escalado, y challengeConfig para controlar su apariencia.
• Tras superarlo, verifica detail.token (más challenge_id/cid) en tu propio backend — no confíes únicamente en el indicador passed del lado del cliente.
• Si el visitante supera la verificación adicional, el veredicto entregado a onVerdict lo refleja (se trata como humano).
• El escalado falla en abierto (fail open): si la verificación adicional no se puede cargar o mostrar, el SDK conserva el veredicto original en lugar de bloquear tu página.

INFO

Prevención de fraude nunca decide por ti. Incluso en challenge/flag, tu código sigue teniendo el control de si la visita continúa — el SDK solo expone el veredicto y, opcionalmente, ejecuta la verificación adicional.

Resiliencia

Si el servicio de veredicto es inalcanzable o se produce cualquier error, el SDK devuelve un veredicto degradado (degraded: true) en lugar de hacer fallar tu página. Un veredicto degradado es conservador (is_bot: false, action: record_only) de modo que nunca bloquea usuarios reales. Comprueba verdict.degraded si quieres tratar esas visitas de forma especial.

Próximos pasos

• Referencia del veredicto — cada campo y cómo actuar sobre él
• API de datos — extrae y concilia veredictos del lado del servidor