Instalar chaves baseadas em pontuação em sites

Esta página explica como instalar uma chave com base em pontuação sem desafio no seu site. Com uma chave baseada em pontuação, é possível incluir o reCAPTCHA Enterprise em todo o site sem exigir que os usuários resolvam desafios de CAPTCHA.

Depois de instalar uma chave baseada em pontuação, é necessário criar uma avaliação e receber uma pontuação para cada solicitação. Com base nessa pontuação, é possível entender o nível de risco que as interações do usuário representam e configurar uma resposta adequada. Além disso, a chave baseada em pontuação pode coletar telemetria de atividade do bot para aviso antecipado contra novos ataques ou alvos.

Para melhorar o modelo de risco do reCAPTCHA Enterprise, recomendamos incluir o reCAPTCHA Enterprise em todas as páginas do site. Isso ajuda a entender como usuários reais e bots transitam entre diferentes páginas e ações.

Antes de começar

  1. Prepare seu ambiente para o reCAPTCHA Enterprise.

  2. Crie uma chave com base em pontuação.

    Como alternativa, é possível copiar o ID de uma chave com base em pontuação atual executando uma das seguintes etapas:

    • Para copiar o ID de uma chave atual do console do Google Cloud, faça o seguinte:

      1. Acesse a página do reCAPTCHA Enterprise.

        Acessar o reCAPTCHA Enterprise

      2. Na lista de chaves reCAPTCHA, mantenha o cursor sobre a chave que você quer copiar e clique em .
    • Para copiar o ID de uma chave atual usando a API REST, use o método projects.keys.list.
    • Para copiar o ID de uma chave atual com a CLI gcloud, use o comando gcloud recaptchakeys list.

Insira a chave no seu site

O reCAPTCHA Enterprise funciona melhor quando há contexto sobre as interações no seu site. O reCAPTCHA Enterprise monitora os comportamentos legítimos e abusivos para saber mais sobre essas interações.

Para melhores resultados, instale chaves com base em pontuação nos seguintes locais do seu site:

  • Formulários
  • Ações (interações do usuário)
  • No segundo plano de todas as páginas da Web

As chaves baseadas em pontuação não interrompem os usuários. Assim, é possível executar o reCAPTCHA Enterprise com chaves baseadas em pontuação sempre que necessário sem afetar as conversões.

Integrar a chave ao front-end

Dependendo de onde você quer adicionar a verificação reCAPTCHA Enterprise, escolha a opção apropriada:

Veja um exemplo de cada opção no código-fonte do site de demonstração.

Adicionar a verificação durante uma interação do usuário

  1. Para carregar o reCAPTCHA Enterprise na sua página da Web, adicione a API JavaScript com sua chave baseada em pontuação no elemento <head></head> da página.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    O reCAPTCHA Enterprise usa o idioma do navegador por padrão. Se você quiser especificar um idioma diferente, use o atributo hl=LANG no script. Por exemplo, para usar o francês, especifique o seguinte: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. Para saber mais sobre as linguagens compatíveis, consulte códigos de idioma para o reCAPTCHA Enterprise.

    Se você quiser especificar um local para o selo, use badge=LOCATION como um parâmetro de consulta na tag de script. Por exemplo, www.google.com/recaptcha/enterprise.js?sitekey=KEY_ID&badge=bottomleft. Por padrão, o local é definido como bottomright. Os outros valores possíveis são inline e bottomleft.

  2. Para adicionar a verificação reCAPTCHA Enterprise a uma interação do usuário, faça o seguinte:

    1. Para garantir que grecaptcha.enterprise.execute() seja executado após o carregamento da biblioteca reCAPTCHA, use grecaptcha.enterprise.ready().

    2. Chame grecaptcha.enterprise.execute() em cada interação que você quer proteger com sua chave baseada em pontuação. Especifique um nome significativo para uma interação do usuário no parâmetro action. Para mais orientações, consulte Ações.

      O exemplo abaixo mostra como chamar grecaptcha.enterprise.execute() em uma ação de login:

      <script>
function onClick(e) {
  e.preventDefault();
  grecaptcha.enterprise.ready(async () => {
    const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'LOGIN'});
    // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
    // reCAPTCHA Enterprise to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha-enterprise/docs/create-assessment
  });
}
</script>

      grecaptcha.enterprise.execute() gera um token conforme mostrado no exemplo a seguir: 

      03AGdBq27tvcDrfiRuxQnyKs-SarXVzPODXLlpiwNsLqdm9BSQQRtxhkD-Wv6l2vBSnL_JQd80FZp3IeeF_TxNMrqhyQchk7hmg_ypDctt_F5RTr9zNO9TSDX3Fy0qHQTuaM9E3hrAkA1v1l7D-fCreg7uq8zoudfh1ZRmN49-2iAMAn4E8_ff-nmlLTNGVZmCSyeze-5xM24pM_JhhUVcCMIDKYtDUnr2imxg2ubIqMscCZGUtdXNUO_LRSzuwWDlLyAr3V2nVn29Z48PQa2QzbymEXzO9pCtoGQmY7kiZ8ILfD9DAJSSyUTMwJXVJptUeBmLM341fq_STYZBbPQJ0zYOEDvJoFsIwGMfuphkDet0nK56b0mkzaL8RCRy2oK31Mcx6n3PhGkCnQ6QIhiV5ZVmV1Hz9M3w99zYw6ekc3wPCNMZ6V6x1ApVpIk3reFfByRQ0C0_pRWwbKZHLXQ_oSTI1UI7kyH1VeXngsJAx2l7zcp0hQNipajC4YwL7Jb8X4cCD0NeiaY1YCrI5j87mK5axcMikq460I4niIFeDBlHGF-ndqu3CJstosAur-C_x827f-dPPjA9Vrw8MDb3x4KUb0vbA8xE9mJxPYGY0rPCR27vJ38Voa7DjEBGX9c-iufv5_wfj-yIfIAHy0iijnRLI0CVkWF2-iPdWv7LnkTwL3WKbF_MrEGZXmtyLX9dEZArfxmToeMuSdYkfikkgR2-k4Xzxlz15RbHJuWSAYqEyTTnpUXmOvDuTN92b0kYqbRelcLUI_Shm-8dq9e-L7K6YWQv32gV6NukZKY15dyrJaW10frBgTOGSTTpIyB7MNEL8S27WjWtOb-zWsgimIhoRNfS8BiJWkmK4gTj51m7Wur-qsDbHgV6gXlMvjJs_B7oXX-mKsKhY9ACtwukotBelGYQOvf1RDHjH3Yi1RDfELBY6AkwUK4tq8cACVGpCwa0gKUo-sbORTsGu_r7VTzYo1AaZD5HV4XUm8yoqszel6DmIfkJcI7PfzzvfUJuvMQ1itZSzpzuth3glbKBYsIjbKqG-q8cxtZ7u0l32j46ASo2zlCJWUjwP3W1P7MUenEoIZtjlyTB_tT6Fk8RxGgRv3oLP7NPFJGs9ZGOAl6tBHpZF8Y_FqEOCMKtBl2JYOE5h6_Es3buSdiMm7mtLr64pboGiEColF1vbVvYpyaaqGFPXBM6ekZSXEXLAI0_7rj_fCLgnB21KXfac95vZbM9vyJCASvDcWKwqajQwy5aGMNe9GtbMogYbZfz5UGWAIi24Vd8KSv3qKOOwvzbcw4H0HYdsBXA

  3. Depois que o token for gerado, envie-o para o back-end e crie uma avaliação em dois minutos.

    Para integrações WAF, se você estiver integrando uma chave de token de ação, será necessário anexar o token a um cabeçalho de solicitação predefinido e não criar uma avaliação. Para detalhes, consulte Implementar tokens de ação reCAPTCHA.

Adicionar reCAPTCHA a um botão HTML

  1. Para carregar o reCAPTCHA Enterprise na sua página da Web, adicione a API JavaScript com sua chave baseada em pontuação no elemento <head></head> da página.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    O reCAPTCHA Enterprise usa o idioma do navegador por padrão. Se você quiser especificar um idioma diferente, use o atributo hl=LANG no script. Por exemplo, para usar o francês, especifique o seguinte: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. Para saber mais sobre as linguagens compatíveis, consulte códigos de idioma para o reCAPTCHA Enterprise.

  2. Para adicionar o reCAPTCHA Enterprise a um botão HTML simples, faça o seguinte:

    1. Defina uma função de callback para processar o token.

      <script>
   function onSubmit(token) {
     document.getElementById("demo-form").submit();
   } // Use `requestSubmit()` for extra features like browser input validation.
</script>

      Para mais informações, consulte o método requestSubmit().

    2. Adicione atributos ao botão HTML.

      <button class="g-recaptcha"
data-sitekey="KEY_ID"
data-callback='onSubmit'
data-action='submit'>Submit</button>

      Se você quiser especificar um local para o selo, use o atributo data-badge=LOCATION no elemento que tiver class=g-recaptcha. Por padrão, o local é definido como bottomright. Os outros valores possíveis são inline e bottomleft.

    3. Quando esse botão é usado para enviar um formulário no seu site, o parâmetro POST g-recaptcha-response contém o token de resposta.

  3. Depois que o token for gerado, envie-o para o back-end e crie uma avaliação em dois minutos.

    Para integrações WAF, se você estiver integrando uma chave de token de ação, será necessário anexar o token a um cabeçalho de solicitação predefinido e não criar uma avaliação. Para detalhes, consulte Implementar tokens de ação reCAPTCHA.

A seguir