Instalar chaves baseadas em pontuação em sites

Nesta página, explicamos como instalar uma chave baseada em pontuação sem desafio 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 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ê 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 representam e configurar uma ou mais respostas adequadas. Além disso, a chave baseada em pontuação pode coletar telemetria de atividade de bot para aviso antecipado contra novos ataques ou alvos.

Para melhorar o modelo de risco do reCAPTCHA, recomendamos que você o inclua em todas as páginas do site, porque 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 Google Cloud Fraud Defense.

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

    Como alternativa, você pode copiar o ID de uma chave baseada em pontuação atual seguindo uma destas etapas:

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

      1. Acesse a página do Google Cloud Fraud Defense.

        Acessar o Google Cloud Fraud Defense

      2. Selecione a guia Chaves.
      3. Na lista de chaves reCAPTCHA, encontre 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.

Colocar a chave no seu site

O reCAPTCHA funciona melhor quando tem contexto sobre as interações no seu site. Ele monitora comportamentos legítimos e abusivos para aprender sobre as interações no seu site.

Para melhores resultados, instale chaves baseadas 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. 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 em uma interação do usuário

  1. Para carregar o reCAPTCHA 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 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 disponíveis, consulte os códigos de idioma do reCAPTCHA.

    Se você quiser especificar um local para o distintivo, use badge=LOCATION como um parâmetro de consulta na tag script. Por exemplo, www.google.com/recaptcha/enterprise.js?render=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 em 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 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 token reCAPTCHA ao back-end e crie uma avaliação em até dois minutos.

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

Adicionar o reCAPTCHA a um botão HTML

  1. Para carregar o reCAPTCHA 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 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 disponíveis, consulte os códigos de idioma do reCAPTCHA.

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

    1. Defina uma função de callback para manipular 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 site, o parâmetro POST g-recaptcha-response contém o token de resposta.

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

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

A seguir