在网页上安装通用密钥

本文档介绍了如何安装通用密钥并将其与网页集成。

准备工作

  1. 为 reCAPTCHA 准备环境。

  2. 创建通用密钥并配置网域。

在您的网站上安装通用密钥

如需安装通用密钥并帮助保护您的网页，请选择 Google Cloud Fraud Defense AutoExecute 配置或标准 JavaScript 安装：

AutoExecute 配置

Fraud Defense AutoExecute 可以通过拦截网页上的网络请求来简化前端 JavaScript 集成，从而无需为每个前端操作手动调用 grecaptcha.enterprise.execute()。

  • AutoExecute 仅拦截使用 Fetch API 或 XMLHttpRequest 发起的异步网络请求，包括使用这些 API 的 AJAX 等框架发出的请求。
  • 对于在网页加载时自动加载的资源，不支持 AutoExecute。而是将 AutoExecute 应用于由用户在网页上执行的操作（例如点击登录按钮）触发的网络请求。
  • 为防止 Fraud Defense 质询导致网络超时，请直接将超时应用于请求。对于 Fetch API，请使用 AbortSignal.timeout(n)；对于 XMLHttpRequest，请使用 XMLHttpRequest.timeout 属性。

将脚本标记添加到网页中

如需在网页上加载 reCAPTCHA，请在网页的 <head></head> 元素中添加带有通用密钥的 JavaScript API：

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

Fraud Defense 默认使用浏览器的语言。如果您想指定其他语言，请在脚本中使用 hl=LANG 属性。例如，如需使用法语，请指定以下内容：

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

如需了解支持的语言，请参阅Fraud Defense 的语言代码。

配置受保护的端点

Fraud Defense 脚本会自动与通用密钥的政策配置中定义的网络操作集成。此部分定义了网址路径 (path) 到操作名称 (action) 的映射。

如果 Fraud Defense 脚本检测到对映射路径的异步网络请求，它会拦截该请求，触发风险评估，并可能会在原始请求继续之前向用户显示 CAPTCHA 挑战。生成的响应令牌会自动附加到请求中的 X-Recaptcha-Token 标头。

gcloud

如需检查通用密钥的当前政策配置，请使用 gcloud alpha recaptcha policies describe 命令：

gcloud alpha recaptcha policies describe --key=KEY_ID

如需使用受保护的端点更新政策配置，请创建一个 YAML 文件（例如 POLICY.yaml），用于定义受保护的路径和操作：

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

使用 gcloud alpha recaptcha policies update 命令通过 YAML 文件更新密钥配置：

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

REST API

如需使用 REST API 更新政策配置以定义受保护的端点，请使用 projects.keys.updatePolicy 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 ID
  • KEY_ID：您的通用密钥的 ID

HTTP 方法和网址：

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

请求 JSON 正文：

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

如需发送您的请求，请展开以下选项之一：

如果请求成功，则返回更新后的政策配置。

path 参数支持以下规则的 glob 模式：

  • 必须以 / 开头，且不能为空。
  • 不能是独立的 /* 或 /**，因为如果针对后端发出的每个请求都触发 Fraud Defense，可能会对性能产生负面影响。
  • 通配符 *（匹配单个路径段）和 **（匹配多个路径段）必须占据整个路径段（例如，/api/*/login 或 /api/* 是有效的；/api/login* 是无效的）。
  • ** 通配符只能占据最后一个路径段（例如，/api/** 有效；/api/**/login 无效）。
  • 第三方请求：如果网页上运行的第三方工具（例如分析或合作伙伴脚本）向与受保护端点匹配的路径（例如，https://analytics.example.net/login与 /login 匹配）发送请求，AutoExecute也会拦截这些请求。这可能会导致额外的网络延迟、指标出现偏差或出现意外的人机识别系统挑战。为避免冲突，请确保受保护的路径具有独特性（例如，/auth/v1/login），或者在发生路径冲突时使用标准安装。
  • 跨网域 API：如果您的后端 API 托管在与网站不同的网域上（例如，examplecdn.net 与 www.example.com），AutoExecute 会自动运行，无需额外的网域配置。

如果您的集成需要针对特定目标网域进行匹配，请提交功能请求。

在后端中，从 X-Recaptcha-Token 请求标头中获取响应令牌，并在两分钟内创建评估。

标准安装

我们建议您在需要验证的用户互动中添加 Fraud Defense 验证。例如，如果您想验证表单的提交操作，则需要在提交操作中添加欺诈防御验证。

根据您希望添加 Fraud Defense 验证的位置，选择相应的选项：

在用户互动时添加验证

  1. 如需在网页上加载 reCAPTCHA，请在网页的 <head></head> 元素中添加带有通用密钥的 JavaScript API：

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

    Fraud Defense 默认使用浏览器的语言。如果您想指定其他语言，请在脚本中使用 hl=LANG 属性。例如，如需使用法语，请指定以下内容：

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

    如需了解支持的语言，请参阅Fraud Defense 的语言代码。

    如果您想为徽章指定位置，请在脚本标记中使用 badge=LOCATION 作为查询参数。例如 https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft。 默认情况下，位置设置为 bottomright。其他可能的值包括 inline 和 bottomleft。

  2. 如需对用户互动添加 Fraud Defense 验证，请执行以下操作：

    1. 如需确保 grecaptcha.enterprise.execute() 在 Fraud Defense 库加载后运行，请使用 grecaptcha.enterprise.ready()。

    2. 针对要使用通用密钥保护的每次互动调用 grecaptcha.enterprise.execute()。在 action 参数中为用户互动指定一个有意义的名称。如需更多指导，请参阅操作。

      以下示例展示了如何对登录操作调用 grecaptcha.enterprise.execute()：

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

      秒

  3. 令牌生成后，将 reCAPTCHA 令牌发送到您的后端，并在两分钟内创建评估。

在 HTML 按钮上添加 Fraud Defense

  1. 如需在网页上加载 reCAPTCHA，请在网页的 <head></head> 元素中添加带有通用密钥的 JavaScript API：

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

    Fraud Defense 默认使用浏览器的语言。如果您想指定其他语言，请在脚本中使用 hl=LANG 属性。例如，如需使用法语，请指定以下内容：

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

    如需了解支持的语言，请参阅Fraud Defense 的语言代码。

  2. 如需在 HTML 按钮上添加 Fraud Defense，请执行以下操作：

    1. 定义用于处理令牌的回调函数。
    <script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>

    如需了解详情，请参阅 requestSubmit() 方法。

    1. 为 HTML 按钮添加属性。
    <button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>

    如果您想为徽章指定位置，请在具有 class="g-recaptcha" 的元素上使用 data-badge="LOCATION" 属性。默认情况下，位置设置为 bottomright。其他可能的值包括 inline 和 bottomleft。

    1. 使用此按钮在您的网站上提交表单时，g-recaptcha-response POST 参数包含响应令牌。

  3. 令牌生成后，将 reCAPTCHA 令牌发送到您的后端，并在两分钟内创建评估。

后续步骤