---
title: Prevención de fraude — Web SDK
---

# 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

```html
<!-- 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.

```js
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](#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ó. |

::: tip 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](./scenarios/ad-fraud).
:::

## 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`.

```js
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](./verdict-reference).

## 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`:

```js
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](./verdict-reference) — cada campo y cómo actuar sobre él
- [API de datos](./data-api) — extrae y concilia veredictos del lado del servidor