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

Opción	Tipo	Por defecto	Descripción
appKey	string	—	La clave de aplicación de Prevención de fraude (obligatoria).
domain	string	predeterminado del servicio	Endpoint del servicio de veredicto. Déjalo sin definir salvo que se te haya dado un dominio dedicado.
escalate	boolean	false	Permite a Prevención de fraude pedir al visitante una verificación adicional cuando una visita parece de alto riesgo. Consulta Escalado.
collectWindowMs	number	1200	Cuánto tiempo (ms) observa el SDK la visita antes de solicitar un veredicto. Ventanas más largas producen un veredicto más fiable a costa de un pequeño retraso.
onVerdict	(v) => void	—	Se invoca una vez con el veredicto final. El principal punto de integración.
onError	(err) => void	—	Se invoca si algo sale mal. El SDK nunca lanza excepciones hacia tu página.
onEscalate	(displayType) => void	—	Se invoca cuando se muestra una verificación adicional (solo cuando escalate: true).
onEscalateDone	(passed) => void	—	Se invoca tras finalizar la verificación adicional; passed es true si el visitante la superó.

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 es opcional (opt-in).

Actívalo con escalate: true:

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // an extra verification is being shown to the visitor
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // visitor cleared the extra check — treat as human
    } else {
      // not cleared — keep the original verdict's recommendation
    }
  },
  onVerdict: function (verdict) {
    // if the visitor cleared escalation, verdict.is_bot is updated to 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.
• 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