Instale chaves baseadas em pontuação em Websites

Esta página explica como instalar uma chave baseada em pontuação sem desafio no seu Website. Com uma chave baseada em pontuação, pode incluir o reCAPTCHA em todo o seu site sem exigir que os utilizadores resolvam desafios CAPTCHA.

Quando uma chave baseada em pontuação é instalada, o reCAPTCHA envia uma resposta encriptada, o token de resposta do reCAPTCHA (também conhecido como token), quando um utilizador final aciona uma interação. Depois de gerar o token, tem de criar uma avaliação no prazo de dois minutos para receber uma pontuação para cada pedido. Com base na pontuação, pode compreender o nível de risco que as interações dos utilizadores representam e configurar uma resposta (ou respostas) adequada. Além disso, a chave baseada em pontuação pode recolher telemetria de atividade de bots para aviso prévio contra novos ataques ou alvos.

Para melhorar o modelo de risco do reCAPTCHA, recomendamos que inclua o reCAPTCHA em todas as páginas do seu site, uma vez que ajuda a compreender como os utilizadores reais e os bots transitam entre diferentes páginas e ações.

Antes de começar

  1. Prepare o seu ambiente para o reCAPTCHA.

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

    Em alternativa, pode copiar o ID de uma chave baseada em pontuação existente realizando um dos seguintes passos:

    • Para copiar o ID de uma chave existente a partir da Google Cloud consola, faça o seguinte:

      1. Aceda à página reCAPTCHA.

        Aceder ao reCAPTCHA

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

Coloque a chave no seu Website

O reCAPTCHA funciona melhor quando tem contexto acerca das interações no seu site. O reCAPTCHA monitoriza o comportamento legítimo e abusivo para saber mais sobre as interações no seu site.

Para ter os melhores resultados, instale as chaves baseadas em pontuação nos seguintes locais do seu Website:

  • Forms
  • Ações (interações do utilizador)
  • No fundo de todas as páginas Web

As chaves baseadas em pontuação não interrompem os seus utilizadores, pelo que pode executar o reCAPTCHA com chaves baseadas em pontuação sempre que necessário sem afetar a conversão.

Integre a chave com o front-end

Recomendamos que adicione a validação reCAPTCHA a uma interação do utilizador que precise de ser validada. Por exemplo, se quiser validar a ação de envio de um formulário, tem de adicionar a validação reCAPTCHA à ação de envio.

Consoante o local onde quer adicionar a validação reCAPTCHA, escolha a opção adequada:

Pode ver um exemplo de cada opção no código fonte do Website de demonstração.

Adicione a validação numa interação do utilizador

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

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

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

    Se quiser especificar uma localização para o emblema, use badge=LOCATION como um parâmetro de consulta na etiqueta de script. Por exemplo, www.google.com/recaptcha/enterprise.js?sitekey=KEY_ID&badge=bottomleft. Por predefinição, a localização está definida como bottomright. Os outros valores possíveis são inline e bottomleft.

  2. Para adicionar a validação reCAPTCHA a uma interação do utilizador, faça o seguinte:

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

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

      O exemplo seguinte mostra como chamar grecaptcha.enterprise.execute() numa ação de início de sessão:

      <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, como mostrado no exemplo seguinte: 

      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 de o token ser gerado, envie-o para o seu back-end e crie uma avaliação no prazo de dois minutos.

    Para integrações de WAF, se estiver a integrar uma chave de token de ação, tem de anexar o token a um cabeçalho de pedido predefinido e não precisa de criar uma avaliação. Para obter detalhes, consulte o artigo Implemente tokens de ação do reCAPTCHA.

Adicione o reCAPTCHA a um botão HTML

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

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

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

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

    1. Defina uma função de chamada de retorno 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 seu botão HTML.

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

      Se quiser especificar uma localização para o emblema, use o atributo data-badge=LOCATION no elemento que tem class=g-recaptcha. Por predefinição, a localização está definida como bottomright. Os outros valores possíveis são inline e bottomleft.

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

  3. Depois de o token ser gerado, envie-o para o seu back-end e crie uma avaliação no prazo de dois minutos.

    Para integrações de WAF, se estiver a integrar uma chave de token de ação, tem de anexar o token a um cabeçalho de pedido predefinido e não precisa de criar uma avaliação. Para obter detalhes, consulte o artigo Implemente tokens de ação do reCAPTCHA.

O que se segue?