---
title: Fraud Prevention — Рекламный фрод
---

# Рекламный фрод

Это **руководство по сценарию**. Базовая интеграция неизменна — вы загружаете
[Web SDK](../web-sdk), читаете [вердикт](../verdict-reference) и получаете данные из
[Data API](../data-api) ровно так, как описано на тех страницах. Эта страница добавляет
лишь ту немногую специфику, которая нужна только сценарию рекламного фрода.

Защита от рекламного фрода отфильтровывает ботов и недействительный трафик из платных
кампаний, чтобы рекламодатели и рекламные площадки платили за подлинные клики и показы,
а не за фейковый объём. От остальных сценариев применения её отличает то, что
**посетителя доставляет третья сторона**, и обеим сторонам нужно сойтись на
независимом выводе «человек / бот» по каждому клику.

## Блокировка в реальном времени у источника

Fraud Prevention работает inline в точке входа и возвращает вердикт в реальном времени — это не отчёт постфактум. Тот, кому принадлежит страница, на которую попадает посетитель, может действовать по этому вердикту немедленно:

- **Рекламодатели** запускают SDK на лендинге: недействительный трафик распознаётся — и при желании ему предъявляется challenge — в момент прибытия, прежде чем он попадёт в воронку или исказит отчётность.
- **Трафик-платформы** запускают SDK на собственной pre-lander или странице редиректа: клик проверяется *до* того, как он будет перенаправлен, поэтому боты останавливаются на входе и никогда не превращаются в доставленный трафик.

Единственное требование — страница, способная запустить SDK: вердикту нужны сигналы браузера, поэтому у чистого серверного 302 нет места, чтобы их собрать — добавьте лёгкую промежуточную страницу, и применится та же блокировка в реальном времени.

Подписанный click-токен и Data API стоят сверху для сверки между обеими сторонами; inline-блокировка в реальном времени — основной механизм, а постфактумная очистка через API — запасной вариант для трафика без промежуточной страницы.

## Две роли

- **Рекламодатель (Advertiser)** — владеет лендингом, на который попадает посетитель.
  Запускает Web SDK на этой странице, чтобы получить вердикт для каждого приходящего
  визита, и получает вердикты из Data API, чтобы сверить то, за что ему выставили счёт.
- **Провайдер (Provider, источник трафика / рекламы)** — доставляет клик. Ему нужно
  **доказать качество того, что он отправил**, поэтому он выпускает click-токен на
  каждый клик, а затем сопоставляет свой отчёт о доставке с независимыми вердиктами.

Обе стороны аутентифицируются в [Data API](../data-api) собственными учётными данными
приложения и читают один и тот же вердикт по каждому клику — именно это позволяет им
сверяться, не доверяя сырым логам друг друга.

## Сквозной поток

Приведённая ниже последовательность показывает, как один клик проходит путь от
доставки провайдером, через посетителя и лендинг рекламодателя, до единого вердикта,
который **оба аккаунта затем читают каждый со своей стороны**.

```mermaid
sequenceDiagram
    autonumber
    participant P as Провайдер (аккаунт B)
    participant V as Посетитель
    participant A as Страница рекламодателя + SDK
    participant F as Fraud Prevention API

    P->>P: Подписать click_token (bot_kid + secret, несёт pkid)
    P->>V: Доставить ссылку с ?_ctk=click_token
    V->>A: Клик → переход на страницу рекламодателя (URL несёт _ctk)
    A->>A: SDK читает _ctk из URL
    A->>F: Зашифрованный POST /bot/verify<br/>(app_key = рекламодатель, click_token = подписан провайдером)
    F->>F: app_key → advertiser_app_id,<br/>проверить pkid → provider_app_id, вынести вердикт,<br/>записать одну строку с обоими app_id
    F-->>A: verdict → onVerdict
    A->>A: Обработать по verdict.action (запись / блок / challenge)

    Note over P,F: Сверка (между аккаунтами)
    A->>F: GET /v1/bot с App-Key рекламодателя
    F-->>A: Та же строка (сопоставлена по advertiser_app_id)
    P->>F: GET /v1/bot с App-Key провайдера
    F-->>P: Та же строка (сопоставлена по provider_app_id)
```

Решающее свойство: **оба app_id живут в одной строке.** Рекламодатель читает её по
совпадению `advertiser_app_id`, провайдер читает её по совпадению `provider_app_id` —
два разных аккаунта, каждый запрашивает со своим собственным App-Key, и оба приходят к
одному и тому же независимому вердикту. Ни одной из сторон не нужно раскрывать или
доверять сырым логам другой, чтобы согласиться о том, что произошло по данному клику.

## Click-токены

**Click-токен (click token)** связывает доставленный провайдером клик с вердиктом,
который в итоге получает визит. Это идентификатор по каждому клику, на котором сходятся
обе стороны. Остальным сценариям применения Fraud Prevention click-токены не нужны —
они сверяют вердикты и без них.

Поток:

1. **Выпуск** — провайдер получает подписанный click-токен (по одному на клик), когда
   направляет посетителя на лендинг рекламодателя.
2. **Перенос на целевой URL** — добавьте выпущенный токен к лендинговому URL как
   query-параметр:

   ```
   https://advertiser.example/lp?click_token=ct_xxxxxxxx
   ```

3. **Чтение на странице** — [Web SDK](../web-sdk) автоматически читает токен из URL.
   Если вы используете другое имя параметра, задайте `tokenParam`:

   ```js
   BotSignal.init({ appKey: 'YOUR_APP_KEY', tokenParam: 'click_token' });
   ```

4. **Сверка** — позже найдите клик через Data API и сопоставьте его обратно с отчётом
   провайдера о доставке.

::: info
Токен уже подписан, когда выдаётся вам, — вам нужно лишь **донести его до лендингового
URL**. Ничего подписывать или вычислять на вашей стороне не требуется.
:::

### Опция `tokenParam`

В этом сценарии Web SDK получает одну дополнительную опцию:

| Опция | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `tokenParam` | string | автоопределение | Имя query-параметра URL, который несёт click-токен провайдера (например, `click_token`). SDK читает его из URL страницы и связывает вердикт с этим кликом. Оставьте без изменений, если вы не используете click-токены. |

## Сверка и взаиморасчёт

Как только визиты несут click-токен, обе стороны рассчитываются на основе одних и тех
же независимых вердиктов:

- **Получить вердикт одного клика** — например, чтобы оспорить или подтвердить один
  клик:

  ```bash
  GET /v1/bot/verdict?click_token=ct_xxx
  X-App-Key: YOUR_APP_KEY
  X-App-Secret: YOUR_APP_SECRET
  ```

- **Экспортировать строки по каждому клику** — получите период времени и сопоставьте
  `click_token` каждой строки обратно со своими логами кликов:

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

  Каждая строка несёт `click_token` визита (когда он присутствует), временную метку и
  поля вердикта (`is_bot`, `score`, `level`, `action`).

Рекламодатель исключает помеченные и ботовые клики из того, за что он платит; провайдер
сверяет свой отчёт о доставке с теми же выводами. Поскольку обе стороны читают **один и
тот же независимый вердикт**, взаиморасчёт не зависит от сырых логов ни одной из сторон.

## Модель безопасности

`cid` и click-токен передаются в URL, поэтому относитесь к ним как к идентификаторам, а не как к учётным данным:

- **Чтение вердикта требует App-Key + App-Secret.** Data API аутентифицирует каждый вызов вашим app secret (сравнение за постоянное время) и возвращает только строки, где ваше приложение является advertiser или provider. Сама по себе `cid` ничего не извлекает — третья сторона, скопировавшая её из URL, не имеет secret и не является участником этой строки.
- **provider связан подписью.** Click-токен подписан по HMAC секретом provider и несёт `pkid` provider; его нельзя подделать, а одну `cid` можно заявить только один раз (защита от повтора).
- **Опционально привяжите и advertiser.** Подпишите `app_key` целевого advertiser в токен как `aud`. Тогда проверка требует, чтобы app_key страницы совпадал с `aud`, поэтому токен, выпущенный для advertiser A, не сможет приписать вердикт advertiser B. Опустите `aud` — и любая страница advertiser сможет принять токен.

Итоговый эффект: вердикт по `cid` доступен для чтения только двум привязанным к нему приложениям — advertiser, чья страница запустила SDK, и provider, чей токен был предъявлен, — каждое из которых аутентифицируется собственным App-Secret.

## Дальнейшие шаги

- [Web SDK](../web-sdk) — собирайте вердикты на лендинге
- [Справочник по вердиктам](../verdict-reference) — каждое поле и как на него реагировать
- [Data API](../data-api) — получение и сверка вердиктов на стороне сервера