---
title: Fraud Prevention — Web SDK
---

# Fraud Prevention Web SDK

Web SDK сервиса Fraud Prevention работает на **вашей странице** — это может быть
лендинг, экран регистрации или входа либо любой защищаемый ресурс. Он запрашивает
вердикт для текущего визита и возвращает его вашему коду, чтобы вы могли решить, что
делать с этим трафиком: записать его, отметить или попросить посетителя пройти одну
дополнительную проверку.

## Быстрый старт

```html
<!-- Загрузка SDK Fraud Prevention -->
<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 — см. Справочник по вердиктам
      if (verdict.is_bot) {
        // исключить этот визит из воронки / подавить конверсии
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>
```

`BotSignal.init()` также возвращает `Promise<BotVerdict>`, поэтому вместо `onVerdict`
вы можете использовать `await` — оба способа получают один и тот же объект вердикта.

```js
const verdict = await BotSignal.init({ appKey: 'YOUR_APP_KEY' });
```

## Опции

| Опция | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `appKey` | string | — | Ключ вашего приложения Fraud Prevention (обязательно). |
| `domain` | string | значение по умолчанию | Эндпоинт сервиса вердиктов. Оставьте без изменений, если только вам не выдали выделенный домен. |
| `escalate` | boolean | `false` | Разрешить Fraud Prevention запросить у посетителя **одну дополнительную проверку**, когда визит выглядит высокорисковым. См. [Эскалацию](#escalation). |
| `collectWindowMs` | number | `1200` | Как долго (мс) SDK наблюдает за визитом, прежде чем запросить вердикт. Более длинное окно даёт более уверенный вердикт ценой небольшой задержки. |
| `onVerdict` | `(v) => void` | — | Вызывается один раз с итоговым вердиктом. Основная точка интеграции. |
| `onError` | `(err) => void` | — | Вызывается, если что-то пошло не так. SDK никогда не выбрасывает исключение в вашу страницу. |
| `onEscalate` | `(displayType) => void` | — | Вызывается при показе дополнительной проверки (только при `escalate: true`). |
| `onEscalateDone` | `(passed) => void` | — | Вызывается после завершения дополнительной проверки; `passed` равно `true`, если посетитель её прошёл. |

::: tip Сценарии с источником трафика
Если посетителей вам доставляет третья сторона и обеим сторонам нужно свериться на
основе вывода по каждому клику, SDK также может прочитать click-токен из URL страницы.
Это специфично для сценариев платного трафика — см. руководство
[Рекламный фрод](./scenarios/ad-fraud).
:::

## Использование вердикта

`onVerdict` получает объект `BotVerdict`. Два поля, которые вы будете использовать
чаще всего:

- **`verdict.is_bot`** — `true`, когда визит признан автоматизированным/недействительным.
- **`verdict.action`** — что мы рекомендуем сделать: `record_only`, `challenge` или
  `flag`.

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // трафик выглядит нормально — продолжаем, просто логируем вердикт
        break;
      case 'flag':
        // подозрительно — продолжаем показывать страницу, но помечаем визит как низкокачественный
        markLowQuality(verdict);
        break;
      case 'challenge':
        // высокий риск — обрабатывается эскалацией, если она включена (см. ниже)
        break;
    }
  },
});
```

Полный список полей и рекомендуемую обработку см. в
[Справочнике по вердиктам](./verdict-reference).

## Эскалация {#escalation}

Когда визит выглядит высокорисковым, Fraud Prevention может попросить посетителя
выполнить **одну дополнительную проверку**, прежде чем вы будете относиться к нему как
к реальному пользователю. Это опционально.

Включите её через `escalate: true`:

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // посетителю показывается дополнительная проверка
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // посетитель прошёл дополнительную проверку — относимся как к человеку
    } else {
      // не прошёл — сохраняем рекомендацию исходного вердикта
    }
  },
  onVerdict: function (verdict) {
    // если посетитель прошёл эскалацию, verdict.is_bot обновляется на false
  },
});
```

Примечания:

- Эскалация срабатывает, только когда `action` вердикта равно `challenge`. Для всех
  остальных визитов ничего не показывается, и опыт посетителя остаётся нетронутым.
- Если посетитель проходит дополнительную проверку, вердикт, переданный в `onVerdict`,
  отражает это (визит считается человеком).
- Эскалация **работает по принципу fail open**: если дополнительную проверку не удаётся
  загрузить или показать, SDK сохраняет исходный вердикт, а не блокирует вашу страницу.

::: info
Fraud Prevention никогда не принимает решение *за* вас. Даже при `challenge`/`flag` ваш
код остаётся хозяином того, продолжится ли визит, — SDK лишь предоставляет вердикт и,
опционально, запускает дополнительную проверку.
:::

## Отказоустойчивость

Если сервис вердиктов недоступен или возникает любая ошибка, SDK возвращает
**деградированный (degraded)** вердикт (`degraded: true`), а не ломает вашу страницу.
Деградированный вердикт консервативен (`is_bot: false`, `action: record_only`), поэтому
никогда не блокирует реальных пользователей. Проверяйте `verdict.degraded`, если хотите
обрабатывать такие визиты особым образом.

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

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