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

option	type	default	Descrição
appKey	string	—	Obrigatório. Sua chave de aplicação da Prevenção de Fraude.
domain	string	signal-v1.world-dynamic.com	Domínio de sinal para o qual o SDK envia as requisições.
tokenParam	string	_ctk	Parâmetro de consulta da URL de onde o SDK lê o token de clique.
onVerdict	(v) => void	—	Chamado uma vez com o veredito final. O principal ponto de integração. init() também retorna Promise<BotVerdict>.
onError	(err) => void	—	Chamado em qualquer falha. O SDK nunca lança exceções para a sua página.
onChallenge	(v) => creds | null | Promise<…>	—	Sobrescreve as credenciais de escalonamento: retorne suas próprias { appKey, serverToken } (serverToken emitido pelo seu backend), ou null para pular o escalonamento. Se não definido, são usadas as credenciais padrão emitidas pelo backend em verdict.escalate (sem configuração).
challengeConfig	object	—	Aparência/posicionamento do captcha: product (popup/float/embed), container, theme, lang.
onEscalate	(displayType) => void	—	Chamado quando um captcha de escalonamento é exibido.
onEscalateDone	(passed, detail) => void	—	Chamado após o escalonamento. passed = o visitante o concluiu; detail = { token, challengeId, cid } para a verificação no lado do servidor da aprovação.

O escalonamento é dirigido pelo servidor. O SDK exibe um captcha apenas quando o action do veredito do servidor é challenge e a aplicação está configurada com uma ação de escalonamento correspondente — não há um interruptor no lado do cliente para isso. Use onChallenge para fornecer suas próprias credenciais ou para pular o escalonamento, e challengeConfig para controlar sua aparência. Depois que um visitante for aprovado, verifique o resultado no seu próprio backend com detail.token (mais challenge_id/cid) — não confie apenas na flag passed do lado do cliente.

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 é dirigido pelo veredito do servidor, não por uma flag no lado do cliente — é executado sempre que o action do veredito é challenge e a aplicação tem uma ação de escalonamento configurada.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // uma verificação extra está sendo exibida ao visitante
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // o visitante concluiu a verificação extra — verifique detail.token no seu backend
    } else {
      // não concluído — mantenha a recomendação do veredito original
    }
  },
  onVerdict: function (verdict) {
    // se o visitante concluiu o escalonamento, verdict.is_bot é atualizado para 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.
• Por padrão, o SDK usa as credenciais emitidas pelo backend em verdict.escalate (sem configuração). Use onChallenge para fornecer suas próprias { appKey, serverToken } ou para pular o escalonamento, e challengeConfig para controlar sua aparência.
• Após uma aprovação, verifique detail.token (mais challenge_id/cid) no seu próprio backend — não confie apenas na flag passed do lado do cliente.
• 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