Instalar chaves baseadas em pontuação em sites

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

Quando uma chave baseada em pontuação é instalada, o reCAPTCHA envia uma resposta criptografada, o token de resposta do reCAPTCHA (também conhecido como token), quando um usuário final aciona uma interação. Depois que o token for gerado, você vai precisar criar uma avaliação em até dois minutos para receber uma pontuação para cada solicitação. Com base na pontuação, é possível entender o nível de risco que as interações do usuário têm e configurar uma ou mais respostas adequadas. Além disso, a chave baseada em pontuação pode coletar telemetria de atividade de bots para aviso antecipado de novos ataques ou alvos.

Para melhorar o modelo de risco do reCAPTCHA, recomendamos incluir o reCAPTCHA 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.

  2. Crie uma chave baseada em pontuação.

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

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

      1. Acesse a página do reCAPTCHA.

        Acessar o reCAPTCHA

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

Inserir a chave no seu site

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

Para ter os melhores resultados, instale as chaves de pontuação nos seguintes locais do 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. Portanto, é possível executar o reCAPTCHA com chaves baseadas em pontuação sempre que necessário, sem afetar a conversão.

Integrar a chave ao front-end

Recomendamos adicionar a verificação reCAPTCHA a uma interação do usuário que precisa ser verificada. Por exemplo, se você quiser verificar a ação de envio de um formulário, adicione a verificação reCAPTCHA à ação de envio.

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

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

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

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

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

    O reCAPTCHA 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 os idiomas aceitos, consulte códigos de idioma para reCAPTCHA.

    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 a uma interação do usuário, faça o seguinte:

    1. Para garantir que grecaptcha.enterprise.execute() seja executado depois que a biblioteca do reCAPTCHA for carregada, use grecaptcha.enterprise.ready().

    2. Chame grecaptcha.enterprise.execute() em cada interação que você quer proteger com a 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 a seguir 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 to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha/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 até dois minutos.

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

Adicionar o reCAPTCHA a um botão HTML

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

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

    O reCAPTCHA 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 os idiomas aceitos, consulte códigos de idioma para reCAPTCHA.

  2. Para adicionar o reCAPTCHA 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 tem 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 até dois minutos.

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

A seguir