Instalar chaves universais em páginas da Web

Este documento descreve como instalar e integrar uma chave universal às suas páginas da Web.

Antes de começar

  1. Prepare seu ambiente para o reCAPTCHA.

  2. Crie uma chave universal e configure domínios.

Instalar chaves universais no seu site

Para instalar sua chave universal e ajudar a proteger suas páginas da Web, escolha a configuração AutoExecute do Google Cloud Fraud Defense ou a instalação JavaScript padrão:

Configuração AutoExecute

O AutoExecute do Fraud Defense pode ajudar a simplificar a integração do JavaScript de front-end interceptando solicitações de rede nas suas páginas da Web, eliminando a necessidade de chamar grecaptcha.enterprise.execute() manualmente para cada ação de front-end.

  • O AutoExecute só intercepta solicitações de rede assíncronas iniciadas com a API Fetch ou XMLHttpRequest, incluindo solicitações de frameworks como o AJAX que usam essas APIs.
  • O AutoExecute não é compatível com recursos que são carregados automaticamente no momento do carregamento da página. Em vez disso, aplique o AutoExecute a solicitações de rede acionadas por ações do usuário na página, como um botão de login.
  • Para evitar que os desafios do Fraud Defense causem tempos limite de rede, aplique tempos limite diretamente às solicitações. Use AbortSignal.timeout(n) para a API Fetch e a propriedade XMLHttpRequest.timeout para XMLHttpRequest.

Adicionar a tag script às suas páginas da Web

Para carregar o reCAPTCHA na sua página da Web, adicione a API JavaScript com a chave universal no elemento <head></head> da sua página:

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

O Fraud Defense usa o idioma do navegador por padrão. Se você quiser especificar um idioma diferente, use o hl=LANG atributo no script. Por exemplo, para usar o francês, especifique o seguinte:

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

Para saber mais sobre os idiomas aceitos, consulte Códigos de idioma para o Fraud Defense.

Configurar endpoints protegidos

O script do Fraud Defense é integrado automaticamente às ações de rede definidas na configuração de política da sua chave universal. Esta seção define um mapeamento de caminhos de URL (path) para nomes de ações (action).

Se o script do Fraud Defense detectar uma solicitação de rede assíncrona para um caminho mapeado, ele vai interceptar a solicitação, acionar uma avaliação de risco e, possivelmente, mostrar um desafio de CAPTCHA ao usuário antes que a solicitação original continue. O token de resposta gerado é anexado automaticamente ao cabeçalho X-Recaptcha-Token na solicitação.

gcloud

Para inspecionar a configuração de política atual da sua chave universal, use o gcloud alpha recaptcha policies describe comando:

gcloud alpha recaptcha policies describe --key=KEY_ID

Para atualizar a configuração de política com seus endpoints protegidos, crie um arquivo YAML (por exemplo, POLICY.yaml) definindo seus caminhos e ações protegidos:

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

Atualize a configuração da chave com o arquivo YAML usando o gcloud alpha recaptcha policies update comando:

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

API REST

Para atualizar a configuração de política para definir endpoints protegidos usando a API REST, use o projects.keys.updatePolicy método.

Antes de usar os dados da solicitação abaixo, faça estas substituições:

  • PROJECT_ID: ID do seu Google Cloud projeto
  • KEY_ID: o ID da sua chave universal

Método HTTP e URL: 

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

Corpo JSON da solicitação: 

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

Para enviar a solicitação, expanda uma destas opções:

Se for bem-sucedida, a solicitação vai retornar a configuração de política atualizada.

O parâmetro path aceita padrões glob com as seguintes regras:

  • Precisa começar com / e não pode estar vazio.
  • Não pode ser um /* ou /** independente, porque pode afetar negativamente a performance ao acionar o Fraud Defense em todas as solicitações para o back-end.
  • Os caracteres curinga * (que correspondem a um único segmento de caminho) e ** (que correspondem a vários segmentos de caminho) precisam ocupar todo um segmento de caminho (por exemplo, /api/*/login ou /api/* são válidos; /api/login* é inválido).
  • O caractere curinga ** só pode ocupar o último segmento de caminho (por exemplo, /api/** é válido; /api/**/login é inválido).
  • Solicitações de terceiros: se ferramentas de terceiros em execução na sua página (como scripts de análise ou de parceiros) enviarem solicitações para caminhos que correspondam aos seus endpoints protegidos (por exemplo, https://analytics.example.net/login correspondendo a /login), AutoExecute também vai interceptá-las. Isso pode causar latência de rede extra, métricas distorcidas ou desafios de CAPTCHA inesperados. Para evitar conflitos, verifique se os caminhos protegidos são distintos (por exemplo, /auth/v1/login) ou use a instalação padrão se ocorrerem colisões de caminho.
  • APIs de domínio cruzado:se a API de back-end estiver hospedada em um domínio diferente do seu site (por exemplo, examplecdn.net em vez de www.example.com), o AutoExecute vai funcionar automaticamente sem configuração de domínio extra.

Se a correspondência com domínios de destino específicos for importante para sua integração, registre uma solicitação de recurso.

No back-end, receba o token de resposta do X-Recaptcha-Token cabeçalho da solicitação e crie uma avaliação em dois minutos.

Instalação padrão

Recomendamos que você adicione a verificação do Fraud Defense a uma interação do usuário que precisa ser verificada. Por exemplo, se você quiser verificar a ação de envio de um formulário, adicione a verificação do Fraud Defense à ação de envio.

Dependendo de onde você quer adicionar a verificação do Fraud Defense, escolha a opção apropriada:

Adicionar verificação a uma interação do usuário

  1. Para carregar o reCAPTCHA na sua página da Web, adicione a API JavaScript com a chave universal no elemento <head></head> da sua página:

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

    O Fraud Defense usa o idioma do navegador por padrão. Se você quiser especificar um idioma diferente, use o hl=LANG atributo no script. Por exemplo, para usar o francês, especifique o seguinte:

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

    Para saber mais sobre os idiomas aceitos, consulte Códigos de idioma para o Fraud Defense.

    Se você quiser especificar um local para o selo, use badge=LOCATION como um parâmetro de consulta na tag script. Por exemplo, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Por padrão, o local é definido como bottomright. Outros valores possíveis são inline e bottomleft.

  2. Para adicionar a verificação do Fraud Defense a uma interação do usuário, faça o seguinte:

    1. Para garantir que grecaptcha.enterprise.execute() seja executado após o carregamento da biblioteca do Fraud Defense, use grecaptcha.enterprise.ready().

    2. Chame grecaptcha.enterprise.execute() em cada interação que você quer proteger com a chave universal. Especifique um nome significativo para uma interação do usuário no parâmetro action. Para mais orientações, consulte Ações.

      O exemplo a seguir mostra como chamar grecaptcha.enterprise.execute() em uma ação de login:

      <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

  3. Depois que o token for gerado, envie o token reCAPTCHA para o back-end e crie uma avaliação em dois minutos.

Adicionar o Fraud Defense a um botão HTML

  1. Para carregar o reCAPTCHA na sua página da Web, adicione a API JavaScript com a chave universal no elemento <head></head> da sua página:

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

    O Fraud Defense usa o idioma do navegador por padrão. Se você quiser especificar um idioma diferente, use o hl=LANG atributo no script. Por exemplo, para usar o francês, especifique o seguinte:

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

    Para saber mais sobre os idiomas aceitos, consulte Códigos de idioma para o Fraud Defense.

  2. Para adicionar o Fraud Defense a um botão HTML, faça o seguinte:

    1. Defina uma função de callback para processar o token.
    <script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>

    Para mais informações, consulte o método requestSubmit().

    1. Adicione atributos ao botão HTML.
    <button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>

    Se você quiser especificar um local para o selo, use o data-badge="LOCATION" atributo no elemento que tem class="g-recaptcha". Por padrão, o local é definido como bottomright. Outros valores possíveis são inline e bottomleft.

    1. Quando esse botão é usado para enviar um formulário no site, o parâmetro POST g-recaptcha-response contém o token de resposta.

  3. Depois que o token for gerado, envie o token reCAPTCHA para o back-end e crie uma avaliação em dois minutos.

A seguir