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

本頁說明如何在網站上安裝核取方塊金鑰，並加入「我不是機器人」核取方塊驗證問題。建立核取方塊金鑰時，視您設定的驗證問題安全性選項而定，reCAPTCHA 可能會要求使用者先回答 CAPTCHA 驗證問題，再產生有效權杖。

事前準備

1. 準備 Google Cloud Fraud Defense 環境。

2. 建立核取方塊索引鍵。

   或者，您也可以執行下列任一步驟，複製現有核取方塊鍵的 ID：

   • 如要從 Google Cloud 控制台複製現有金鑰的 ID，請按照下列步驟操作：

     1. 前往 Google Cloud Fraud Defense 頁面。

        前往 Google Cloud Fraud Defense

     2. 選取「金鑰」分頁標籤。
     3. 在 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 屬性，並將其設為動作名稱。如需更多指引，請參閱動作。

重要事項： 您指定的操作會做為評估的一部分傳回。您必須確認評估的 JSON 回應中的動作，與建立評估時指定的預期動作相符。舉例來說，登入動作應在登入頁面上傳回。如果不相符，表示有攻擊者企圖假冒正常操作。

指令碼必須使用 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"></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。

如要明確顯示小工具，請按照下列步驟操作：

1. 如要延遲轉譯小工具，請按照下列步驟操作：

   1. 請先指定 onload 回呼函式，再載入 reCAPTCHA API 和其他依附元件。

       <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：指定與受保護元素相關聯的動作名稱。

        重要事項： 您指定的動作會做為評估的一部分傳回。您必須確認評估的 JSON 回應中的動作，與您在建立評估時指定的預期動作相符。舉例來說，登入動作應在登入頁面上傳回。如果不相符，代表有攻擊者企圖假冒正常操作。

      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">
    </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',
          'action': 'LOGIN',
        });
      };
    </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">
    </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',
          'action': 'action1',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.enterprise.render(document.getElementById('example2'), {
          'sitekey' : 'KEY_ID',
          'action': 'action2',
        });
        grecaptcha.enterprise.render('example3', {
          'sitekey' : 'KEY_ID',
          'action': 'action3',
          '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">
    </script>
  </body>
</html>

後續步驟

• 如要評估 reCAPTCHA 回應權杖，請建立評估。