Instala claves basadas en puntuaciones en sitios web

En esta página, se explica cómo instalar una clave basada en puntuaciones sin ningún desafío en tu sitio web. Con una clave basada en puntuaciones, puedes incluir reCAPTCHA Enterprise en todo el sitio sin que los usuarios deban resolver desafíos de CAPTCHA.

Después de instalar una clave basada en puntuaciones, debes crear una evaluación y recibir una puntuación para cada solicitud. Según la puntuación, puedes comprender el nivel de riesgo que representan las interacciones de los usuarios y configurar una respuesta (o respuestas) adecuada. Además, la clave basada en puntuaciones puede recopilar la telemetría de actividad del bot para obtener una advertencia temprana de ataques o objetivos nuevos.

Para mejorar el modelo de riesgo de reCAPTCHA Enterprise, te recomendamos que incluyas reCAPTCHA Enterprise en cada página de tu sitio porque ayuda a comprender cómo los usuarios reales y bots realizan la transición entre diferentes páginas y acciones.

Antes de comenzar

  1. Prepara tu entorno para reCAPTCHA Enterprise.

  2. Crea una clave basada en puntuaciones.

    Como alternativa, puedes copiar el ID de una clave existente basada en puntuaciones si realizas 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.

Coloca la llave en tu sitio web

reCAPTCHA Enterprise funciona mejor cuando tiene contexto sobre las interacciones en tu sitio. reCAPTCHA Enterprise supervisa tanto el comportamiento legítimo como el abusivo para conocer las interacciones en tu sitio.

Para obtener mejores resultados, instala claves basadas en puntuaciones en los siguientes lugares de tu sitio web:

  • Formularios
  • Acciones (interacciones del usuario)
  • En segundo plano en todas las páginas web

Las claves basadas en puntuaciones no interrumpen a tus usuarios, por lo que puedes ejecutar reCAPTCHA Enterprise con claves basadas en puntuaciones siempre que sea necesario sin afectar la conversión.

Integra la clave al frontend

Según dónde quieras agregar la verificación de reCAPTCHA Enterprise, elige la opción correspondiente:

Puedes ver un ejemplo de cada opción en el código fuente del sitio web de demostración.

Cómo agregar la verificación a una interacción del usuario

  1. Para cargar reCAPTCHA Enterprise en tu página web, agrega la API de JavaScript con tu clave basada en puntuaciones dentro del elemento <head></head> de tu página web.

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

    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.

    Si deseas especificar una ubicación para la insignia, utiliza badge=LOCATION como parámetro de consulta en la etiqueta de la secuencia de comandos. Por ejemplo, www.google.com/recaptcha/enterprise.js?sitekey=KEY_ID&badge=bottomleft De forma predeterminada, la ubicación se establece en bottomright. Los otros valores posibles son inline y bottomleft.

  2. Para agregar la verificación de reCAPTCHA Enterprise a una interacción del usuario, haz lo siguiente:

    1. Para asegurarte de que grecaptcha.enterprise.execute() se ejecute después de que se cargue la biblioteca de reCAPTCHA, usa grecaptcha.enterprise.ready().

    2. Llama a grecaptcha.enterprise.execute() en cada interacción que desees proteger con tu clave basada en puntuaciones. Especifica un nombre significativo para una interacción del usuario en el parámetro action. Para obtener más información, consulta Acciones.

      En el siguiente ejemplo, se muestra cómo llamar a grecaptcha.enterprise.execute() en una acción de acceso:

      <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 Enterprise to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha-enterprise/docs/create-assessment
  });
}
</script>

      grecaptcha.enterprise.execute() genera un token, como se muestra en el siguiente ejemplo: 

      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. Después de generar el token, envía el token de reCAPTCHA a tu backend y crea una evaluación en dos minutos.

    Para las integraciones de WAF, si integras una clave de token de acción, debes adjuntar el token a un encabezado de solicitud predefinido y no necesitas crear una evaluación. Para obtener más información, consulta Implementa tokens de acción de reCAPTCHA.

Agrega reCAPTCHA en un botón HTML

  1. Para cargar reCAPTCHA Enterprise en tu página web, agrega la API de JavaScript con tu clave basada en puntuaciones dentro del elemento <head></head> de tu página web.

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

    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.

  2. Para agregar reCAPTCHA Enterprise a un botón HTML simple, haz lo siguiente:

    1. Define una función de devolución de llamada para controlar el token.

      <script>
   function onSubmit(token) {
     document.getElementById("demo-form").submit();
   } // Use `requestSubmit()` for extra features like browser input validation.
</script>

      Para obtener más información, consulta el método requestSubmit().

    2. Agrega atributos al botón HTML.

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

      Si deseas especificar una ubicación para la insignia, usa el atributo data-badge=LOCATION en el elemento que tiene class=g-recaptcha. De forma predeterminada, la ubicación se establece en bottomright. Los otros valores posibles son inline y bottomleft.

    3. Cuando se usa este botón para enviar un formulario en tu sitio, el parámetro g-recaptcha-response POST contiene el token de respuesta.

  3. Después de generar el token, envía el token de reCAPTCHA a tu backend y crea una evaluación en dos minutos.

    Para las integraciones de WAF, si integras una clave de token de acción, debes adjuntar el token a un encabezado de solicitud predefinido y no necesitas crear una evaluación. Para obtener más información, consulta Implementa tokens de acción de reCAPTCHA.

¿Qué sigue?