Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Instalar claves universales en páginas web

En este documento, se describe cómo puedes instalar e integrar una llave universal en tus páginas web.

Antes de comenzar

Instala claves universales en tu sitio web

Para instalar tu clave universal y proteger tus páginas web, elige la configuración de AutoExecute de Google Cloud Fraud Defense o la instalación estándar de JavaScript:

Configuración de AutoExecute

Fraud Defense AutoExecute puede ayudarte a simplificar la integración de JavaScript en el frontend, ya que intercepta las solicitudes de red en tus páginas web, lo que elimina la necesidad de llamar a grecaptcha.enterprise.execute() de forma manual para cada acción del frontend.

AutoExecute solo intercepta las solicitudes de red asíncronas iniciadas con la API de Fetch o XMLHttpRequest, incluidas las solicitudes de frameworks como AJAX que usan estas APIs.
AutoExecute no es compatible con los recursos que se cargan automáticamente en el tiempo de carga de la página. En su lugar, aplica AutoExecute a las solicitudes de red que se activan por las acciones del usuario en la página, como un botón de acceso.
Para evitar que los desafíos de Defensa contra fraudos provoquen tiempos de espera de red, aplica tiempos de espera directamente a las solicitudes. Usa AbortSignal.timeout(n) para la API de Fetch y la propiedad XMLHttpRequest.timeout para XMLHttpRequest.

Agrega la etiqueta de secuencia de comandos a tus páginas web

Para cargar reCAPTCHA en tu página web, agrega la API de JavaScript con tu clave universal 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, Fraud Defense usa el idioma del navegador. Si quieres especificar un idioma diferente, usa el atributo hl=LANG en tu secuencia de comandos. Por ejemplo, para usar francés, especifica lo siguiente:

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

Para obtener información sobre los idiomas admitidos, consulta los códigos de idioma para Fraud Defense.

Configura extremos protegidos

La secuencia de comandos de Defensa contra el fraude se integra automáticamente con las acciones de red definidas en la configuración de la política de tu clave universal. En esta sección, se define una asignación de rutas de URL (path) a nombres de acciones (action).

Si el script de Fraud Defense detecta una solicitud de red asíncrona a una ruta asignada, intercepta la solicitud, activa una evaluación de riesgos y, posiblemente, muestra un desafío CAPTCHA al usuario antes de que continúe la solicitud original. El token de respuesta generado se adjunta automáticamente al encabezado X-Recaptcha-Token de la solicitud.

gcloud

Para inspeccionar la configuración de política actual de tu clave universal, usa el comando gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

Para actualizar la configuración de la política con tus extremos protegidos, crea un archivo YAML (por ejemplo, POLICY.yaml) que defina tus rutas y acciones protegidas:

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Actualiza la configuración de tu clave con el archivo YAML usando el comando gcloud alpha recaptcha policies update:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

API de REST

Para actualizar la configuración de la política y definir extremos protegidos con la API de REST, usa el método projects.keys.updatePolicy.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: ID del proyecto de Google Cloud
KEY_ID: Es el ID de tu clave universal.

Método HTTP y URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

Cuerpo JSON de la solicitud:

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup" | Select-Object -Expand Content

Si la solicitud se realiza correctamente, se devuelve la configuración de política actualizada.

El parámetro path admite patrones glob con las siguientes reglas:

Debe comenzar con / y no puede estar vacío.
No puede ser un /* o /** independiente, ya que puede afectar negativamente el rendimiento si se activa Fraud Defense en cada solicitud a tu backend.
Los comodines * (que coinciden con un solo segmento de ruta) y ** (que coinciden con varios segmentos de ruta) deben ocupar la totalidad de un segmento de ruta (por ejemplo, /api/*/login o /api/* son válidos; /api/login* no es válido).
El comodín ** solo debe ocupar el último segmento de la ruta de acceso (por ejemplo, /api/** es válido; /api/**/login no es válido).

Solicitudes de terceros: Si las herramientas de terceros que se ejecutan en tu página (como las estadísticas o las secuencias de comandos de socios) envían solicitudes a rutas que coinciden con tus extremos protegidos (por ejemplo, https://analytics.example.net/login que coincide con /login), AutoExecute también las interceptará. Esto puede causar latencia de red adicional, métricas sesgadas o desafíos de CAPTCHA inesperados. Para evitar conflictos, asegúrate de que tus rutas protegidas sean distintivas (por ejemplo, /auth/v1/login) o usa la instalación estándar si se producen colisiones de rutas.
APIs de varios dominios: Si tu API de backend está alojada en un dominio diferente al de tu sitio web (por ejemplo, examplecdn.net en lugar de www.example.com), AutoExecute funciona automáticamente sin configuración de dominio adicional.

Si es importante que la integración coincida con dominios de destino específicos, presenta una solicitud de función.

En tu backend, obtén el token de respuesta del encabezado de la solicitud X-Recaptcha-Token y crea una evaluación en un plazo de dos minutos.

Instalación estándar

Te recomendamos que agregues la verificación de Fraud Defense en una interacción del usuario que deba verificarse. Por ejemplo, si deseas verificar la acción de envío de un formulario, debes agregar la verificación de Defensa contra fraudos en la acción de envío.

Según dónde quieras agregar la verificación de Fraud Defense, elige la opción adecuada:

Agrega una verificación en una interacción del usuario
Agrega Fraud Defense a un botón HTML

Agrega verificación en una interacción del usuario

Para cargar reCAPTCHA en tu página web, agrega la API de JavaScript con tu clave universal 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, Fraud Defense usa el idioma del navegador. Si quieres especificar un idioma diferente, usa el atributo hl=LANG en tu secuencia de comandos. Por ejemplo, para usar francés, especifica lo siguiente:

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

Para obtener información sobre los idiomas admitidos, consulta los códigos de idioma para Fraud Defense.

Si deseas especificar una ubicación para la insignia, usa badge=LOCATION como parámetro de consulta en la etiqueta de secuencia de comandos. Por ejemplo, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. De forma predeterminada, la ubicación se establece en bottomright. Otros valores posibles son inline y bottomleft.
Para agregar la verificación de Fraud Defense en 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 Fraud Defense, usa grecaptcha.enterprise.ready().
2. Llama a grecaptcha.enterprise.execute() en cada interacción que quieras proteger con tu clave universal. Especifica un nombre significativo para una interacción del usuario en el parámetro action. Para obtener más orientación, consulta Acciones.
  
  Nota: Agrega la llamada execute a acciones sensibles, como LOGIN, SIGNUP, PASSWORD_RESET o PURCHASE.
  
  En el siguiente ejemplo, se muestra cómo llamar a grecaptcha.enterprise.execute() en una acción de acceso:
```
<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  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 Fraud Defense 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>
```
  s
Después de generar el token, envía el token de reCAPTCHA a tu backend y crea una evaluación en un plazo de dos minutos.

Importante: Tu backend debe especificar assessment.event.expected_action (o expectedAction en JSON) en CreateAssessmentRequest, y debe coincidir con la acción configurada en la llamada execute(). Por ejemplo, si configuras la acción de frontend como LOGIN, tu backend debe establecer expected_action en LOGIN cuando crees una evaluación para esa solicitud. Si no hay coincidencia, indica que un atacante está intentando falsificar acciones.

Cómo agregar Fraud Defense a un botón HTML

Para cargar reCAPTCHA en tu página web, agrega la API de JavaScript con tu clave universal 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, Fraud Defense usa el idioma del navegador. Si quieres especificar un idioma diferente, usa el atributo hl=LANG en tu secuencia de comandos. Por ejemplo, para usar francés, especifica lo siguiente:

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

Para obtener información sobre los idiomas admitidos, consulta los códigos de idioma para Fraud Defense.
Para agregar Fraud Defense a un botón HTML, 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().
1. Agrega atributos a tu 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. Otros valores posibles son inline y bottomleft.
1. Cuando se usa este botón para enviar un formulario en tu sitio, el parámetro POST g-recaptcha-response contiene el token de respuesta.
Nota: Si configuras el botón g-recaptcha como disabled, el botón se habilitará cuando se cargue Fraud Defense.
Después de generar el token, envía el token de reCAPTCHA a tu backend y crea una evaluación en un plazo de dos minutos.

Importante: Tu backend debe especificar assessment.event.expected_action (o expectedAction en JSON) en CreateAssessmentRequest, y debe coincidir con la acción configurada en el botón. Por ejemplo, si configuras la acción del botón como submit, tu backend debe establecer expected_action en submit cuando crees una evaluación para esa solicitud. Si no hay coincidencia, indica que un atacante está intentando falsificar acciones.

¿Qué sigue?

Para activar los desafíos de CAPTCHA en función de reglas personalizadas, configura políticas de desafío.
Para evaluar el token de respuesta de reCAPTCHA, crea una evaluación.