Instalar chaves de caixa de seleção (desafio de caixa de seleção) em sites

Nesta página, explicamos como instalar uma chave de caixa de seleção com o desafio Não sou um robô no seu site. Dependendo de como você configurou a opção de segurança do desafio ao criar a chave da caixa de seleção, o reCAPTCHA Enterprise pode exigir que o usuário final resolva um desafio captcha antes de gerar um token válido.

Antes de começar

Prepare seu ambiente para o reCAPTCHA Enterprise.
Crie uma chave de caixa de seleção.

Como alternativa, é possível copiar o ID de uma chave de caixa de seleçã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.

Renderizar o widget reCAPTCHA no front-end

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

Com esse método, é possível renderizar o widget em qualquer objeto (como div ou span) com a classe g-recaptcha.

Na página da 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 o defina como sua chave de caixa de seleçã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 deve ser carregado usando o protocolo HTTPS e pode ser incluído em qualquer ponto da página sem restrição.

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.

O exemplo a seguir é um snippet de exemplo de código:

    <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>

Com esse método, é possível renderizar o widget por um script JavaScript atual usando o método grecaptcha.enterprise.render(). Use esse método para evitar disputas ou se quiser mostrar o widget com base na lógica atual do JavaScript.

Para garantir que não haja disputas ao renderizar o widget explicitamente, analise as considerações a seguir:

Primeiro, ordene seus scripts com a função de callback e, depois, com a API reCAPTCHA Enterprise.
Use os parâmetros async e defer nas tags script.

Para renderizar o widget explicitamente, siga estas etapas:

Para adiar a renderização do widget, faça o seguinte:
1. Especifique sua função de callback onload antes do carregamento da API reCAPTCHA Enterprise e de outras dependências.
```
 <script type="text/javascript">
 var onloadCallback = function() {
    alert("grecaptcha is ready!");
 };
 </script>
```
2. Depois que a função de callback for 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 contêiner (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: especifica o nome da ação associado ao elemento protegido.
    
    Importante: a ação especificada é retornada como parte da avaliação. Verifique se a ação na resposta JSON da avaliação corresponde à ação esperada que você especificou ao criar uma avaliação. Por exemplo, uma ação de login precisa ser retornada na página de login. Se houver uma incompatibilidade, isso indica que um invasor está tentando falsificar ações.
```
grecaptcha.enterprise.render('html_element', {
   'sitekey' : ' KEY_ID',
   'action': 'LOGIN',
 });
```
Para renderizar o widget, insira o recurso JavaScript. Defina onload como o nome da função de callback onload e inclua render=explicit.

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.
```
 <script src="https://www.google.com/recaptcha/enterprise.js?onload=onload_Callback_function&render=explicit"
    async defer>
 </script>
```

Exemplo 1

O exemplo de código a seguir mostra a renderização explícita após um callback 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 exemplo de código a seguir 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>

A seguir

Para avaliar o token de resposta reCAPTCHA, crie uma avaliação.