在網站中安裝核取方塊金鑰 (核取方塊驗證)

本頁說明如何在網站上安裝核取方塊金鑰，並使用「我不是機器人」核取方塊驗證方式。建立核取方塊金鑰時，您可以設定驗證問題安全選項。視設定而定，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 小工具，請使用下列其中一種方法：

自動算繪小工具

使用這個方法，您可以在任何物件 (例如 div 或 span) 上，以 g-recaptcha 類別算繪小工具。

在網頁上，加入必要的 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>

明確轉譯小工具

使用這個方法，您可以透過現有的 JavaScript 指令碼，使用 grecaptcha.enterprise.render() 方法算繪小工具。使用這個方法可避免競爭狀況，或根據現有的 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() 方法。

      • container：用於轉譯 reCAPTCHA 小工具的 HTML 元素。 指定容器的 ID (字串) 或 DOM 元素本身。

      • parameters：含有參數的物件，以鍵/值組合表示，例如 {"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>

後續步驟