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' });

Опции

option	type	default	Описание
appKey	string	—	Обязательно. Ключ вашего приложения Fraud Prevention.
domain	string	signal-v1.world-dynamic.com	Домен сигнала, на который SDK отправляет запросы.
tokenParam	string	_ctk	URL-параметр запроса, из которого SDK читает click-токен.
onVerdict	(v) => void	—	Вызывается один раз с итоговым вердиктом. Основная точка интеграции. init() также возвращает Promise<BotVerdict>.
onError	(err) => void	—	Вызывается при любой ошибке. SDK никогда не выбрасывает исключение в вашу страницу.
onChallenge	(v) => creds | null | Promise<…>	—	Переопределить учётные данные эскалации: верните свои { appKey, serverToken } (serverToken выдаётся вашим бэкендом) или null, чтобы пропустить эскалацию. Если не задано, используются учётные данные по умолчанию, выданные бэкендом, в verdict.escalate (без конфигурации).
challengeConfig	object	—	Внешний вид и размещение капчи: product (popup/float/embed), container, theme, lang.
onEscalate	(displayType) => void	—	Вызывается при показе капчи эскалации.
onEscalateDone	(passed, detail) => void	—	Вызывается после эскалации. passed = посетитель её прошёл; detail = { token, challengeId, cid } для серверной верификации прохождения.

Эскалация управляется сервером. SDK показывает капчу только тогда, когда action вердикта сервера равно challenge и приложение настроено с соответствующим действием эскалации — клиентского переключателя для этого нет. Используйте onChallenge, чтобы передать свои учётные данные или пропустить эскалацию, и challengeConfig, чтобы управлять её внешним видом. После того как посетитель прошёл проверку, верифицируйте результат на своём собственном бэкенде с помощью detail.token (плюс challenge_id/cid) — не доверяйте одному только клиентскому флагу passed.

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

Если посетителей вам доставляет третья сторона и обеим сторонам нужно свериться на основе вывода по каждому клику, 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 может попросить посетителя выполнить одну дополнительную проверку, прежде чем вы будете относиться к нему как к реальному пользователю. Это управляется вердиктом сервера, а не клиентским флагом — оно запускается всякий раз, когда action вердикта равно challenge и в приложении настроено действие эскалации.

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

Примечания:

• Эскалация срабатывает, только когда action вердикта равно challenge. Для всех остальных визитов ничего не показывается, и опыт посетителя остаётся нетронутым.
• По умолчанию SDK использует учётные данные, выданные бэкендом, в verdict.escalate (без конфигурации). Используйте onChallenge, чтобы передать свои { appKey, serverToken } или пропустить эскалацию, и challengeConfig, чтобы управлять её внешним видом.
• После прохождения верифицируйте detail.token (плюс challenge_id/cid) на своём собственном бэкенде — не доверяйте одному только клиентскому флагу passed.
• Если посетитель проходит дополнительную проверку, вердикт, переданный в onVerdict, отражает это (визит считается человеком).
• Эскалация работает по принципу fail open: если дополнительную проверку не удаётся загрузить или показать, SDK сохраняет исходный вердикт, а не блокирует вашу страницу.

INFO

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

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

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

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

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