Instalar teclas de casillas de verificación (desafío de casilla de verificación) en sitios web

En esta página, se explica cómo instalar una clave de casilla de verificación con el desafío de casilla de verificación I'm not a robot en tu sitio web. Según cómo hayas configurado la opción de seguridad del desafío cuando creaste la clave de casilla de verificación, reCAPTCHA Enterprise podría requerir que el usuario final resuelva un desafío de CAPTCHA antes de generar un token válido.

Antes de comenzar

Prepara tu entorno para reCAPTCHA Enterprise.
Crea una clave de casilla de verificación.

Como alternativa, puedes copiar el ID de una clave de casilla de verificación existente mediante uno de los siguientes pasos:
- Para copiar el ID de una clave existente desde Google Cloud Console, haz lo siguiente:
  1. Ve a la página de reCAPTCHA Enterprise.
    
    Ir a reCAPTCHA Enterprise
  2. En la lista de claves de reCAPTCHA, mantén el puntero sobre la clave que deseas copiar y haz clic en .
- Para copiar el ID de una clave existente con la API de REST, usa el método projects.keys.list.
- Para copiar el ID de una clave existente con la CLI de gcloud, usa el comando gcloud recaptcha keys list.

Renderiza el widget de reCAPTCHA en el frontend

Para mostrar el widget de reCAPTCHA en tu página web, usa uno de los siguientes métodos:

Con este método, puedes renderizar el widget en cualquier objeto (como un div o un span) con la clase g-recaptcha.

En tu página web, incluye el recurso de JavaScript necesario y un elemento HTML con la clase g-recaptcha.

En el elemento con la clase g-recaptcha, incluye también el atributo data-sitekey y configúralo del mismo modo que tu clave de casilla de verificación.

Para especificar una acción, incluye el atributo data-action y configúralo con un nombre de acción. Para obtener más información, consulta Acciones.

La secuencia de comandos debe cargarse mediante el protocolo HTTPS y puede incluirse desde cualquier punto de la página sin restricciones.

De forma predeterminada, reCAPTCHA Enterprise usa el idioma del navegador. Si deseas especificar un idioma diferente, usa el atributo hl=LANG en la secuencia de comandos. Por ejemplo, para usar francés, especifica lo siguiente: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. Para obtener información sobre los idiomas compatibles, consulta los códigos de idioma de reCAPTCHA Enterprise.

El siguiente ejemplo es un fragmento de código de muestra:

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

Con este método, puedes renderizar el widget a través de una secuencia de comandos de JavaScript existente con el método grecaptcha.enterprise.render(). Usa este método para evitar condiciones de carrera o si deseas mostrar el widget según la lógica de JavaScript existente.

Para asegurarte de que no haya condiciones de carrera cuando renderices el widget de forma explícita, revisa las siguientes consideraciones:

Ordena tus secuencias de comandos con la función de devolución de llamada primero y, luego, con la API de reCAPTCHA Enterprise.
Usa los parámetros async y defer en las etiquetas script.

Para renderizar el widget de forma explícita, sigue estos pasos:

Para diferir la renderización del widget, haz lo siguiente:
1. Especifica la función de devolución de llamada onload antes de que se carguen la API de reCAPTCHA Enterprise y otras dependencias.
```
 <script type="text/javascript">
 var onloadCallback = function() {
    alert("grecaptcha is ready!");
 };
 </script>
```
2. Después de ejecutar la función de devolución de llamada, llama al método grecaptcha.enterprise.render() con los siguientes parámetros de la API de JavaScript.
  - conteiner: El elemento HTML para renderizar el widget reCAPTCHA. Especifica el ID del contenedor (string) o el elemento DOM en sí.
  - parameters: Es un objeto que contiene parámetros como pares clave-valor, por ejemplo, {"sitekey": " KEY_ID", "theme": "light"}.
  - action: Especifica el nombre de la acción asociado con el elemento protegido.
    
    Importante: La acción que especifiques se mostrará como parte de la evaluación. Debes verificar que la acción en la respuesta JSON de la evaluación coincida con la acción esperada que especificas cuando creas una evaluación. Por ejemplo, se debe mostrar una acción de acceso en tu página de acceso. Si hay una discrepancia, indica que un atacante intenta falsificar acciones.
```
grecaptcha.enterprise.render('html_element', {
   'sitekey' : ' KEY_ID',
   'action': 'LOGIN',
 });
```
Para renderizar el widget, inserta el recurso de JavaScript. Configura onload con el nombre de la función de devolución de llamada en carga y, además, incluye render=explicit.

De forma predeterminada, reCAPTCHA Enterprise usa el idioma del navegador. Si deseas especificar un idioma diferente, usa el atributo hl=LANG en la secuencia de comandos. Por ejemplo, para usar francés, especifica lo siguiente: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. Para obtener información sobre los idiomas compatibles, consulta los códigos de idioma de reCAPTCHA Enterprise.
```
 <script src="https://www.google.com/recaptcha/enterprise.js?onload=onload_Callback_function&render=explicit"
    async defer>
 </script>
```

Ejemplo 1

En la siguiente muestra de código, se muestra una renderización explícita después de una devolución de llamada de 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>

Ejemplo 2

En la siguiente muestra de código, se presenta un procesamiento explícito de varios 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>

¿Qué sigue?

Para evaluar el token de respuesta de reCAPTCHA, crea una evaluación.