Instale chaves de caixas de verificação (desafio de caixas de verificação) em Websites

Esta página explica como instalar uma chave de caixa de verificação com o desafio da caixa de verificação Não sou um robô no seu Website. Consoante a forma como configurou a opção de segurança do desafio ao criar a chave de caixa de verificação, o reCAPTCHA pode exigir que o utilizador final resolva um desafio CAPTCHA antes de gerar um token válido.

Antes de começar

  1. Prepare o seu ambiente para o reCAPTCHA.

  2. Crie uma chave de caixa de verificação.

    Em alternativa, pode copiar o ID de uma chave de caixa de verificação existente através de 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.

Renderize o widget reCAPTCHA no frontend

Para apresentar o widget reCAPTCHA na sua página Web, use um dos seguintes métodos:

Renderizar automaticamente o widget

Com este método, pode renderizar o widget em qualquer objeto (como um div ou um span) com a classe g-recaptcha.

Na sua página Web, inclua o recurso JavaScript necessário e um elemento HTML com a classe g-recaptcha.

No elemento com a classe g-recaptcha, inclua também o atributo data-sitekey e defina-o como igual à chave da caixa de verificação.

Para especificar uma ação, inclua o atributo data-action e defina-o como um nome de ação. Para mais orientações, consulte Ações.

O script tem de ser carregado através do protocolo HTTPS e pode ser incluído em qualquer ponto da página sem restrições.

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.

O exemplo seguinte é um fragmento de código de exemplo:

    <html>
      <head>
        <title>reCAPTCHA demo: Simple page</title>
        <script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
      </head>
      <body>
        <form action="?" method="POST">
          <div class="g-recaptcha" data-sitekey="KEY_ID" data-action="LOGIN"></div>
          <br/>
          <input type="submit" value="Submit">
        </form>
      </body>
    </html>

Renderize o widget explicitamente

Com este método, pode renderizar o widget através de um script JavaScript existente com o método grecaptcha.enterprise.render(). Use este método para evitar condições de concorrência ou se quiser mostrar o widget com base na lógica JavaScript existente.

Para garantir que não existem condições de corrida ao renderizar o widget explicitamente, reveja as seguintes considerações:

  • Ordene os seus scripts com a função de chamada de retorno primeiro e, em seguida, a API reCAPTCHA.
  • Use os parâmetros async e defer nas etiquetas script.

Para renderizar o widget explicitamente, siga estes passos:

  1. Para diferir a renderização do widget, faça o seguinte:

    1. Especifique a sua função de callback onload antes de a API reCAPTCHA e outras dependências serem carregadas.

       <script type="text/javascript">
 var onloadCallback = function() {
    alert("grecaptcha is ready!");
 };
 </script>

    2. Depois de a função de chamada de retorno ser executada, chame o método grecaptcha.enterprise.render() com os seguintes parâmetros da API JavaScript.

      • container: o elemento HTML para renderizar o widget reCAPTCHA. Especifique o ID do contentor (string) ou o próprio elemento DOM.

      • parameters: um objeto que contém parâmetros como pares de chave-valor, por exemplo, {"sitekey": "KEY_ID", "theme": "light"}.

      • action: especifique o nome da ação associada ao elemento protegido.

      grecaptcha.enterprise.render('html_element', {
   'sitekey' : 'KEY_ID',
   'action': 'LOGIN',
 });

  2. Para renderizar o widget, insira o recurso JavaScript. Defina onload como o nome da função de chamada de retorno onload e inclua render=explicit.

    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.

     <script src="https://www.google.com/recaptcha/enterprise.js?onload=onload_Callback_function&render=explicit"
    async defer>
 </script>

Exemplo 1

O seguinte exemplo de código mostra a renderização explícita após uma chamada de retorno onload:

<html>
   <head>
    <title>reCAPTCHA demo: Explicit render after an onload callback</title>
     <script type="text/javascript">
      var onloadCallback = function() {
        grecaptcha.enterprise.render('html_element', {
          'sitekey' : 'KEY_ID',
        });
      };
    </script>
  </head>
  <body>
    <form action="?" method="POST">
      <div id="html_element"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
      <script src="https://www.google.com/recaptcha/enterprise.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

Exemplo 2

O seguinte exemplo de código mostra a renderização explícita de vários widgets:

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render for multiple widgets</title>
        <script type="text/javascript">
      var verifyCallback = function(response) {
        alert(response);
      };
      var widgetId1;
      var widgetId2;
      var onloadCallback = function() {
        // Renders the HTML element with id 'example1' as a reCAPTCHA widget.
        // The id of the reCAPTCHA widget is assigned to 'widgetId1'.
        widgetId1 = grecaptcha.enterprise.render('example1', {
          'sitekey' : 'KEY_ID',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.enterprise.render(document.getElementById('example2'), {
          'sitekey' : 'KEY_ID',
        });
        grecaptcha.enterprise.render('example3', {
          'sitekey' : 'KEY_ID',
          'callback' : verifyCallback,
          'theme' : 'dark'
        });
      };
    </script>
  </head>
  <body>
    <!-- The g-recaptcha-response string displays in an alert message upon submit. -->
    <form action="javascript:alert(grecaptcha.enterprise.getResponse(widgetId1));">
      <div id="example1"></div>
      <br>
      <input type="submit" value="getResponse">
    </form>
    <br>
    <!-- Resets reCAPTCHA widgetId2 upon submit. -->
    <form action="javascript:grecaptcha.enterprise.reset(widgetId2);">
      <div id="example2"></div>
      <br>
      <input type="submit" value="reset">
    </form>
    <br>
    <!-- POSTs back to the page's URL upon submit with a g-recaptcha-response POST parameter. -->
    <form action="?" method="POST">
      <div id="example3"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
     <script src="https://www.google.com/recaptcha/enterprise.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

O que se segue?