在网站上安装复选框密钥（复选框挑战）

本页介绍了如何在您的网站上使用我不是机器人复选框来安装复选框密钥。reCAPTCHA 可能会要求最终用户先解决人机识别系统挑战，然后才能生成有效令牌，具体取决于您在创建复选框密钥时配置挑战安全选项的方式。

准备工作

  1. 为 reCAPTCHA 准备环境。

  2. 创建复选框键。

    或者，通过执行以下步骤之一，复制现有复选框键的 ID：

    • 如需从 Google Cloud 控制台复制现有密钥的 ID，请执行以下操作：

      1. 前往 reCAPTCHA 页面。

        前往 reCAPTCHA

      2. 在 reCAPTCHA 密钥列表中，将鼠标指针悬停在要复制的密钥上，然后点击 。
    • 如需使用 REST API 复制现有密钥的 ID，请使用 projects.keys.list 方法。
    • 如需使用 gcloud CLI 复制现有密钥的 ID，请使用 gcloud recaptcha keys list 命令。

在前端呈现 reCAPTCHA 微件

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

自动呈现微件

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

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

在具有 g-recaptcha 类的元素中，还要添加 data-sitekey 属性并将其设置为您的复选框键。

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

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

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

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

    <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 API。
  • 在 script 标签中使用 async 和 defer 参数。

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

  1. 要延迟微件的呈现，请执行以下操作：

    1. 在加载 reCAPTCHA API 和其他依赖项之前，请指定 onload 回调函数。

       <script type="text/javascript">
 var onloadCallback = function() {
    alert("grecaptcha is ready!");
 };
 </script>

    2. 执行回调函数后，请使用 JavaScript API 中的以下参数调用 grecaptcha.enterprise.render() 方法。

      • 容器：用于呈现 reCAPTCHA 微件的 HTML 元素。指定容器的 ID（字符串）或 DOM 元素本身。

      • 参数：一个对象，它包含作为键值对的参数，例如 {"sitekey": "KEY_ID", "theme": "light"}。

      • action：指定与受保护元素关联的操作名称。

      grecaptcha.enterprise.render('html_element', {
   'sitekey' : 'KEY_ID',
   'action': 'LOGIN',
 });

  2. 如需呈现微件，请插入 JavaScript 资源。将 onload 设置为 onload 回调函数的名称，并添加 render=explicit。

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

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

后续步骤