Fraude publicitario

Esta es una guía de escenario. La integración principal no cambia — cargas el Web SDK, lees un veredicto y extraes datos de la API de datos 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 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.

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 lee el token de la URL automáticamente. Si usas un nombre de parámetro diferente, define tokenParam:

   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:

  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:

  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.

Próximos pasos

• Web SDK — recopila veredictos en la landing page
• Referencia del veredicto — cada campo y cómo actuar sobre él
• API de datos — extrae y concilia veredictos del lado del servidor