---
title: Prevención de fraude — Fraude publicitario
---
# Fraude publicitario
Esta es una **guía de escenario**. La integración principal no cambia — cargas el
[Web SDK](../web-sdk), lees un [veredicto](../verdict-reference) y extraes datos de la
[API de datos](../data-api) exactamente como se describe en esas páginas. Esta página
añade los pocos detalles que solo el escenario de fraude publicitario necesita.
La protección contra el fraude publicitario filtra el tráfico de bots e inválido
fuera de las campañas de pago, para que anunciantes y plataformas publicitarias
paguen por clics e impresiones genuinos — no por volumen falso. Lo que lo diferencia
de los otros casos de uso es que **un tercero entrega al visitante**, y ambas partes
necesitan ponerse de acuerdo sobre una conclusión humano / bot independiente y por
clic.
## Bloqueo en tiempo real en el origen
Fraud Prevention se ejecuta inline en el punto de entrada y devuelve un veredicto en tiempo real — no es un informe a posteriori. Quien sea dueño de la página en la que aterriza el visitante puede actuar sobre ese veredicto de inmediato:
- **Los anunciantes** ejecutan el SDK en la landing page: el tráfico inválido se detecta — y, opcionalmente, se le presenta un desafío — en el momento en que llega, antes de que entre en el funnel o distorsione los informes.
- **Las plataformas de tráfico** ejecutan el SDK en su propia pre-lander o página de redirección: un clic se verifica *antes* de ser reenviado, de modo que los bots se detienen en la entrada y nunca se convierten en tráfico entregado.
El único requisito es una página que pueda ejecutar el SDK: un veredicto necesita señales del navegador, así que un 302 puramente del lado del servidor no tiene dónde recogerlas — añade una página intermedia ligera y se aplica el mismo bloqueo en tiempo real.
El token de clic firmado y la Data API se apoyan encima para la conciliación entre ambas partes; el bloqueo inline en tiempo real es el mecanismo principal, y la limpieza posterior vía API es el respaldo para el tráfico sin página intermedia.
## Los dos roles
- **Anunciante (Advertiser)** — es propietario de la landing page a la que llega el
visitante. Ejecuta el Web SDK en esa página para obtener un veredicto por cada
visita entrante, y extrae veredictos de la API de datos para conciliar lo que se le
facturó.
- **Proveedor (Provider)** (fuente de tráfico / publicidad) — entrega el clic.
Necesita **demostrar la calidad de lo que envió**, así que emite un token de clic
por cada clic y luego cruza su informe de entrega contra los veredictos
independientes.
Ambas partes se autentican en la [API de datos](../data-api) con sus propias
credenciales de aplicación y leen el mismo veredicto por clic, que es lo que les
permite conciliar sin confiar en los registros en bruto de la otra.
## Flujo de extremo a extremo
La secuencia a continuación muestra cómo un clic viaja desde la entrega del
proveedor, pasando por el visitante y la landing page del anunciante, hasta un único
veredicto que **ambas cuentas leen después desde su propio lado**.
```mermaid
sequenceDiagram
autonumber
participant P as Proveedor (cuenta B)
participant V as Visitante
participant A as Página del anunciante + SDK
participant F as API de Prevención de fraude
P->>P: Firma click_token (bot_kid + secret, lleva pkid)
P->>V: Entrega el enlace con ?_ctk=click_token
V->>A: Clic → aterriza en la página del anunciante (la URL lleva _ctk)
A->>A: El SDK lee _ctk de la URL
A->>F: POST cifrado /bot/verify
(app_key = anunciante, click_token = firmado por el proveedor)
F->>F: app_key → advertiser_app_id,
verifica pkid → provider_app_id, emite un veredicto,
escribe una fila con ambos app_ids
F-->>A: verdict → onVerdict
A->>A: Gestiona según verdict.action (registrar / bloquear / challenge)
Note over P,F: Conciliación (entre cuentas)
A->>F: GET /v1/bot con la App-Key del anunciante
F-->>A: Misma fila (coincidencia por advertiser_app_id)
P->>F: GET /v1/bot con la App-Key del proveedor
F-->>P: Misma fila (coincidencia por provider_app_id)
```
La propiedad decisiva: **ambos app_ids viven en la misma fila.** El anunciante la lee
con coincidencia por `advertiser_app_id`, el proveedor la lee con coincidencia por
`provider_app_id` — dos cuentas distintas, cada una consultando con su propia
App-Key, cada una llegando al mismo veredicto independiente. Ninguna de las partes
tiene que exponer ni confiar en los registros en bruto de la otra para ponerse de
acuerdo sobre lo que ocurrió en un clic dado.
## Tokens de clic
Un **token de clic** vincula un clic entregado por el proveedor con el veredicto que
la visita finalmente recibe. Es el identificador por clic sobre el que ambas partes
se ponen de acuerdo. Los demás casos de uso de Prevención de fraude no necesitan
tokens de clic — concilian veredictos sin ellos.
El flujo:
1. **Emitir** — el proveedor obtiene un token de clic firmado (uno por cada clic)
cuando enruta un visitante hacia la landing page del anunciante.
2. **Llevarlo en la URL de destino** — añade el token emitido a la URL de aterrizaje
como parámetro de consulta:
```
https://advertiser.example/lp?click_token=ct_xxxxxxxx
```
3. **Leerlo en la página** — el [Web SDK](../web-sdk) lee el token de la URL
automáticamente. Si usas un nombre de parámetro diferente, define `tokenParam`:
```js
BotSignal.init({ appKey: 'YOUR_APP_KEY', tokenParam: 'click_token' });
```
4. **Conciliar** — busca el clic más tarde a través de la API de datos y crúzalo con
el informe de entrega del proveedor.
::: info
El token ya está firmado cuando se te emite — solo necesitas **llevarlo hasta la URL
de aterrizaje**. No hay nada que firmar ni calcular de tu lado.
:::
### Opción `tokenParam`
El Web SDK gana una opción adicional en este escenario:
| Opción | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `tokenParam` | string | autodetectado | Nombre del parámetro de consulta de la URL que lleva el token de clic del proveedor (p. ej. `click_token`). El SDK lo lee de la URL de la página y vincula el veredicto a ese clic. Déjalo sin definir si no usas tokens de clic. |
## Conciliación y liquidación
Una vez que las visitas llevan un token de clic, ambas partes se ponen de acuerdo
sobre los mismos veredictos independientes:
- **Obtener el veredicto de un solo clic** — por ejemplo para disputar o confirmar un
clic:
```bash
GET /v1/bot/verdict?click_token=ct_xxx
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```
- **Exportar filas por clic** — extrae un rango temporal y cruza el `click_token` de
cada fila con tus propios registros de clics:
```bash
GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```
Cada fila lleva el `click_token` de la visita (cuando está presente), la marca de
tiempo y los campos del veredicto (`is_bot`, `score`, `level`, `action`).
El anunciante excluye los clics marcados y de bots de aquello por lo que paga; el
proveedor concilia su informe de entrega contra las mismas conclusiones. Como ambos
leen el **mismo veredicto independiente**, la liquidación no depende de los registros
en bruto de ninguna de las partes.
## Modelo de seguridad
La `cid` y el token de clic viajan en la URL, así que trátalos como identificadores, no como credenciales:
- **Leer un veredicto requiere App-Key + App-Secret.** La Data API autentica cada llamada con tu app secret (comparado en tiempo constante) y solo devuelve filas en las que tu app es el advertiser o el provider. Una `cid` por sí sola no obtiene nada: un tercero que la copia de la URL no tiene secret y no es parte de la fila.
- **El provider queda ligado por firma.** El token de clic está firmado con HMAC usando el secret del provider y lleva el `pkid` del provider; no se puede falsificar, y una `cid` solo puede reclamarse una vez (protegida contra reenvío).
- **Opcionalmente, liga también al advertiser.** Firma el `app_key` del advertiser de destino en el token como `aud`. La verificación exige entonces que el app_key de la página coincida con `aud`, de modo que un token emitido para el advertiser A no pueda atribuir un veredicto en el advertiser B. Omite `aud` y cualquier página de advertiser podrá aceptar el token.
Efecto neto: el veredicto de una `cid` solo es legible por las dos apps ligadas a él —el advertiser cuya página ejecutó el SDK y el provider cuyo token se presentó—, cada una autenticándose con su propio App-Secret.
## Próximos pasos
- [Web SDK](../web-sdk) — recopila veredictos en la landing page
- [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