Fraud Prevention Web SDK

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

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

<!-- Загрузка 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 — оба способа получают один и тот же объект вердикта.

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

Опции

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

Сценарии с источником трафика

Если посетителей вам доставляет третья сторона и обеим сторонам нужно свериться на основе вывода по каждому клику, SDK также может прочитать click-токен из URL страницы. Это специфично для сценариев платного трафика — см. руководство Рекламный фрод.

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

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

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

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

Полный список полей и рекомендуемую обработку см. в Справочнике по вердиктам.

Эскалация

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

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

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, если хотите обрабатывать такие визиты особым образом.

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

• Справочник по вердиктам — каждое поле и как на него реагировать
• Data API — получение и сверка вердиктов на стороне сервера