A tag é um script. Coloque-o no <head> de toda página de onde começa uma ação protegida: a página de cadastro, a de login, o checkout.
<script src="https://korzen.dev/v1/tag.js" data-site-key="YOUR_SITE_KEY" async></script>
Ele carrega de forma assíncrona e nunca trava a página. Observa o comportamento do navegador (input, tempo, o que ele diz sobre si mesmo), envia isso ao Bot Protection e guarda a resposta no cookie _kz do seu domínio. O seu servidor lê esse cookie e o envia na chamada de decisão.
Seus domínios
Não há nada para listar: coloque a tag nas suas páginas, e o Bot Protection aprende os seus domínios com os beacons dela e as chamadas do seu servidor. Um domínio é adicionado em Seus domínios, na página Configuração, na primeira decisão que o seu servidor pede sobre um visitante de uma das páginas dele que não seja um bot. Um domínio conta com todos os subdomínios dele: loja.example, www.loja.example e app.loja.example são um domínio só no seu plano. Páginas em localhost, 127.0.0.1 ou [::1] sempre funcionam, para testes, e nunca entram na lista. O seu plano define quantos domínios ficam protegidos: os primeiros vistos, até esse número. Beacons de uma página em qualquer outro domínio são recusados com 402 até você remover um domínio na página Configuração ou escolher um plano maior; remova ali também um domínio que não é seu, como uma cópia do seu site. No trial grátis, cada domínio tem direito a um único trial grátis: beacons de um domínio que já teve o trial grátis em outra conta são recusados com 402 até você escolher um plano.
Antes da ação
Antes de cada ação protegida, espere pela tag e então envie o formulário:
await window.korzen?.ready();
Ela informa o que o visitante fez desde o último relato da tag: quem espera na página, deixa o navegador preencher o formulário e aperta Enter fez tudo isso depois desse relato. A promise resolve em poucos segundos mesmo quando o Bot Protection está lento ou bloqueado, então um formulário nunca fica preso. Um formulário que o navegador envia sem o seu JavaScript é relatado quando a página sai, o que em geral, não sempre, chega ao Bot Protection antes de o seu servidor perguntar.
Opções
| Atributo | Padrão | O que faz |
|---|---|---|
data-site-key | obrigatório | a sua site key pública |
data-wait-ms | 2500 | quanto tempo a tag observa o input antes de reportar |
data-ready-ms | 2000 | quanto a mais korzen.ready() pode esperar |
O Bot Protection percebe a tag sozinho: assim que uma das suas decisões chega com o token da tag, uma decisão sem o cookie _kz passa a contar como evidência fraca de bot. Até lá, a falta do token não conta nada.
Content Security Policy
Uma página servida com o cabeçalho Content-Security-Policy precisa deixar a tag carregar, enviar o que leu e iniciar o seu worker. Acrescente estas origens às diretivas que a sua política já tem:
script-src https://korzen.dev; connect-src https://korzen.dev; worker-src blob:
Sem worker-src blob:, a tag continua funcionando e todo visitante passa: o Bot Protection só perde um sinal. Uma página sem o cabeçalho não precisa de nada.
O seu aviso de privacidade
Você é o controlador do que a tag lê nas suas páginas, e a Korzen é a sua operadora, sob o Acordo de Tratamento de Dados, que lista os dados e por quanto tempo cada um é guardado. Uma frase que o seu aviso de privacidade pode usar:
“Para proteger cadastros, logins e pagamentos contra bots e fraude, nossas páginas usam o Korzen Bot Protection. Ele lê características técnicas do seu navegador e de como você usa a página, nunca o que você digita, e guarda um identificador aleatório do seu navegador para reconhecer um navegador que volta. Fazemos isso pelo nosso legítimo interesse em prevenir fraudes (considerando 47 do RGPD; art. 10 da LGPD).”
Pelas regras de ePrivacy da UE, o cookie _kz e o local storage da tag podem ser estritamente necessários para a ação que o visitante pediu; você decide isso com os seus assessores, ou pede consentimento (a Política de Cookies lista cada item). Uma ação que você marca com require_token manda um visitante sem token válido para a página de desafio da Korzen, que roda a tag da própria Korzen: a seção 2 do Acordo de Tratamento de Dados diz o que isso significa.