在网站上安装复选框密钥（复选框验证）

本页介绍了如何在您的网站上安装包含我不是机器人复选框验证的复选框密钥。根据您在创建复选框密钥时配置验证安全选项的方式，reCAPTCHA Enterprise 可能会要求最终用户先完成人机识别系统验证，然后才能生成有效令牌。

准备工作

为 reCAPTCHA Enterprise 准备好环境。
创建复选框键。

或者，您也可以通过执行以下步骤之一复制现有复选框键的 ID：
- 如需从 Google Cloud 控制台复制现有密钥的 ID，请执行以下操作：
  1. 转到 reCAPTCHA Enterprise 页面。
    
    转到 reCAPTCHA Enterprise
  2. 在 reCAPTCHA 密钥列表中，将指针悬停在要复制的密钥上，然后点击。
- 如需使用 REST API 复制现有密钥的 ID，请使用 projects.keys.list 方法。
- 如需使用 gcloud CLI 复制现有密钥的 ID，请使用 gcloud recaptcha keys list 命令。

在前端呈现 reCAPTCHA widget

如需在您的网页上显示 reCAPTCHA 微件，请使用以下方法之一：

借助此方法，您可以使用 g-recaptcha 类在任何对象（例如 div 或 span）上呈现微件。

在网页上，添加必要的 JavaScript 资源和带有 g-recaptcha 类的 HTML 元素。

在包含 g-recaptcha 类的元素中，还要添加 data-sitekey 属性，并将其设为与复选框键相等。

如需指定操作，请添加 data-action 属性并将其设置为操作名称。如需获取更多指导，请参阅操作。

该脚本必须使用 HTTPS 协议加载，并且可以从页面的任意位置无限制地添加。

reCAPTCHA Enterprise 默认使用浏览器的语言。如果要指定其他语言，请在脚本中使用 hl=LANG 属性。例如，如需使用法语，请指定以下内容：<script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>。如需了解支持的语言，请参阅 reCAPTCHA Enterprise 的语言代码。

以下示例是一个示例代码段：

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

借助此方法，您可以使用 grecaptcha.enterprise.render() 方法通过现有 JavaScript 脚本来呈现微件。要避免竞态条件，或者想要根据现有 JavaScript 逻辑显示微件，请使用此方法。

为确保在明确呈现微件时不存在竞态条件，请查看以下注意事项：

先使用回调函数对脚本进行排序，然后再使用 reCAPTCHA Enterprise API。
在 script 标签中使用 async 和 defer 参数。

要明确呈现微件，请按以下步骤操作：

要延迟微件的呈现，请执行以下操作：
1. 在加载 reCAPTCHA Enterprise API 和其他依赖项之前，请指定 onload 回调函数。
```
 <script type="text/javascript">
 var onloadCallback = function() {
    alert("grecaptcha is ready!");
 };
 </script>
```
2. 执行回调函数后，请通过 JavaScript API 使用以下参数调用 grecaptcha.enterprise.render() 方法。
  - 容器：用于呈现 reCAPTCHA 微件的 HTML 元素。指定容器（字符串）的 ID 或 DOM 元素本身。
  - parameters：包含键值对形式的参数的对象，例如 {"sitekey": " KEY_ID", "theme": "light"}。
  - action：指定与受保护元素相关联的操作名称。
    
    重要提示 ：您指定的操作会在评估过程中返回。您必须验证评估的 JSON 响应中的操作是否与您在创建评估时指定的预期操作匹配。例如，登录页面上应返回登录操作。如果不一致，则表示攻击者正在试图伪造操作。
```
grecaptcha.enterprise.render('html_element', {
   'sitekey' : ' KEY_ID',
   'action': 'LOGIN',
 });
```
如需呈现该 widget，请插入 JavaScript 资源。将 onload 设置为 onload 回调函数的名称，并添加 render=explicit。

reCAPTCHA Enterprise 默认使用浏览器的语言。如果要指定其他语言，请在脚本中使用 hl=LANG 属性。例如，如需使用法语，请指定以下内容：<script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>。如需了解支持的语言，请参阅 reCAPTCHA Enterprise 的语言代码。
```
 <script src="https://www.google.com/recaptcha/enterprise.js?onload=onload_Callback_function&render=explicit"
    async defer>
 </script>
```

示例 1

以下代码示例展示了 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>

示例 2

以下代码示例展示了多个微件的明确呈现：

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

后续步骤

要评估 reCAPTCHA 响应令牌，请创建评估。

在网站上安装复选框密钥（复选框验证）

准备工作

在前端呈现 reCAPTCHA widget

自动呈现微件

明确呈现微件

后续步骤