Web SDK da Prevenção de Fraude

O Web SDK da Prevenção de Fraude roda na sua página — uma landing page, uma tela de cadastro ou login, ou qualquer recurso protegido. Ele solicita um veredito para a visita atual e o devolve ao seu código, para que você possa decidir o que fazer com o tráfego — registrá-lo, sinalizá-lo ou pedir ao visitante uma verificação extra.

Início rápido

<!-- Load the Fraud Prevention SDK -->
<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 — see Verdict Reference
      if (verdict.is_bot) {
        // exclude this visit from your funnel / suppress conversions
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>

BotSignal.init() também retorna uma Promise<BotVerdict>, então você também pode usar await em vez de onVerdict — ambos recebem o mesmo objeto de veredito.

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

Opções

Opção	Tipo	Padrão	Descrição
appKey	string	—	Sua chave de aplicação da Prevenção de Fraude (obrigatório).
domain	string	padrão do serviço	Endpoint do serviço de veredito. Deixe sem definir, a menos que você tenha recebido um domínio dedicado.
escalate	boolean	false	Permite que a Prevenção de Fraude peça ao visitante uma verificação extra quando uma visita parece de alto risco. Veja Escalonamento.
collectWindowMs	number	1200	Por quanto tempo (ms) o SDK observa a visita antes de solicitar um veredito. Janelas mais longas produzem um veredito mais confiante ao custo de um pequeno atraso.
onVerdict	(v) => void	—	Chamado uma vez com o veredito final. O principal ponto de integração.
onError	(err) => void	—	Chamado se algo der errado. O SDK nunca lança exceções para a sua página.
onEscalate	(displayType) => void	—	Chamado quando uma verificação extra é exibida (somente quando escalate: true).
onEscalateDone	(passed) => void	—	Chamado após a verificação extra terminar; passed é true se o visitante a concluiu.

Cenários de fonte de tráfego

Se um terceiro entrega visitantes a você e ambos os lados precisam conciliar com base em uma conclusão por clique, o SDK também pode ler um token de clique da URL da página. Isso é específico de fluxos de tráfego pago — veja o guia de Fraude em anúncios.

Usando o veredito

onVerdict recebe um objeto BotVerdict. Os dois campos que você mais usará:

• verdict.is_bot — true quando a visita é julgada como automatizada/inválida.
• verdict.action — o que recomendamos que você faça: record_only, challenge ou flag.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // normal-looking traffic — proceed, just log the verdict
        break;
      case 'flag':
        // suspicious — keep serving the page but mark this visit as low quality
        markLowQuality(verdict);
        break;
      case 'challenge':
        // high risk — handled by escalation if enabled (see below)
        break;
    }
  },
});

Veja a lista completa de campos e o tratamento recomendado na Referência de Veredito.

Escalonamento

Quando uma visita parece de alto risco, a Prevenção de Fraude pode pedir ao visitante que conclua uma verificação adicional antes de você tratá-lo como um usuário real. Isso é opcional (opt-in).

Ative com escalate: true:

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // an extra verification is being shown to the visitor
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // visitor cleared the extra check — treat as human
    } else {
      // not cleared — keep the original verdict's recommendation
    }
  },
  onVerdict: function (verdict) {
    // if the visitor cleared escalation, verdict.is_bot is updated to false
  },
});

Observações:

• O escalonamento só é acionado quando o action do veredito é challenge. Para todas as outras visitas nada é exibido e a experiência do visitante permanece intacta.
• Se o visitante concluir a verificação extra, o veredito entregue a onVerdict reflete isso (tratado como humano).
• O escalonamento falha em modo aberto (fail open): se a verificação extra não puder ser carregada ou exibida, o SDK mantém o veredito original em vez de bloquear sua página.

INFO

A Prevenção de Fraude nunca decide por você. Mesmo em challenge/flag, seu código continua no controle de saber se a visita prossegue — o SDK apenas expõe o veredito e, opcionalmente, executa a verificação extra.

Resiliência

Se o serviço de veredito estiver inacessível ou ocorrer qualquer erro, o SDK retorna um veredito degradado (degraded: true) em vez de falhar sua página. Um veredito degradado é conservador (is_bot: false, action: record_only), de modo que nunca bloqueia usuários reais. Verifique verdict.degraded se você quiser tratar essas visitas de forma especial.

Próximos passos

• Referência de Veredito — cada campo e como agir sobre ele
• Data API — obtenha e concilie vereditos no lado do servidor