隱形 reCAPTCHA

本頁面說明如何在網頁上啟用及自訂隱形 reCAPTCHA。

如要叫用隱藏的 reCAPTCHA，您可以採取下列任一做法：

請參閱「設定」一節，瞭解如何自訂隱形 reCAPTCHA。舉例來說，您可以指定語言或標記的位置。

請參閱「驗證使用者的回應」，看看使用者是否已成功通過人機驗證 (CAPTCHA)。

自動將驗證程序繫結至按鈕

在網頁上使用隱形 reCAPTCHA 小工具最簡單的方法，就是加入必要的 JavaScript 資源，並在 HTML 按鈕中加入一些屬性。必要屬性為類別名稱「g-recaptcha」、data-sitekey 屬性中的網站金鑰，以及處理 data-callback 屬性中人機驗證完成作業的 JavaScript 回呼名稱。

<html>
  <head>
    <title>reCAPTCHA demo: Simple page</title>
     <script src="https://www.google.com/recaptcha/api.js" async defer></script>
     <script>
       function onSubmit(token) {
         document.getElementById("demo-form").submit();
       }
     </script>
  </head>
  <body>
    <form id="demo-form" action="?" method="POST">
      <button class="g-recaptcha" data-sitekey="your_site_key" data-callback="onSubmit">Submit</button>
      <br/>
    </form>
  </body>
</html>

指令碼必須使用 HTTPS 通訊協定載入，並可由網頁中的任何位置載入，而不受限制。

以程式輔助方式將挑戰繫結至按鈕或叫用挑戰。

您可以指定 onload 回呼函式，並在 JavaScript 資源中加入參數，藉此延後繫結。這與一般 reCAPTCHA 驗證問題的運作方式相同。

透過程式輔助方式叫用挑戰。

您可以用程式輔助方式叫用 reCAPTCHA 驗證，方法是在包含屬性 data-size="invisible" 的 div 中顯示驗證方式，並以程式輔助方式呼叫執行。

  1. 使用 data-size="invisible" 建立 div。

    <div class="g-recaptcha"
      data-sitekey="_your_site_key_"
      data-callback="onSubmit"
      data-size="invisible">
</div>

  2. 從 JavaScript 方法呼叫 grecaptcha.execute。

    grecaptcha.execute();

    執行回呼後，您可以從 JavaScript API 呼叫 grecaptcha.render 方法。

設定

JavaScript 資源 (api.js) 參數

參數 值 說明
onload 選用設定。在載入所有依附元件後要執行的回呼函式名稱。
render explicit
onload		 選用設定。是否明確算繪小工具。預設為 onload，在第一個找到的 g-recaptcha 標記中算繪小工具。
hl 請參閱語言代碼 選用設定。強制小工具以特定語言顯示。如果未指定語言，系統會自動偵測使用者的語言。

g-recaptcha 標記屬性和 grecaptcha.render 參數

g-recaptcha 標記屬性 grecaptcha.render 參數 值 預設 說明
data-sitekey sitekey 你的網站金鑰。
data-badge 徽章 右下角內嵌 右下角 選用設定。重新放置 reCAPTCHA 徽章的位置。使用「inline」時，您可以使用 CSS 指定位置。
data-size 大小 隱藏 選用設定。用於建立繫結至 div 的隱藏小工具，並透過程式輔助方式執行。
data-tabindex tabindex 0 選用設定。挑戰的分頁索引。如果網頁中的其他元素使用 Tabindex，則應該設定用於方便使用者瀏覽。
data-callback 回呼 選用設定。回呼函式的名稱，會在使用者提交成功回應時執行。g-recaptcha-response 權杖會傳遞至回呼。
data-expired-callback expired-callback 選用設定。回呼函式的名稱，在 reCAPTCHA 回應到期且使用者需要重新驗證時執行。
data-error-callback 錯誤回呼 選用設定。回呼函式名稱。當 reCAPTCHA 遇到錯誤 (通常是網路連線) 時，系統會執行此函式，且在連線恢復前無法繼續執行。如果您在這裡指定函式，則需負責通知使用者應重試。
已隔離 false 選用設定。讓外掛程式擁有者不要幹擾網頁上現有的 reCAPTCHA 安裝作業。如為 true，這個 reCAPTCHA 執行個體就會包含在個別 ID 空間中。

JavaScript API

方法 說明
grecaptcha.render (
容器，
參數，
繼承
) 		將容器算繪為 reCAPTCHA 小工具，並傳回新建立的小工具 ID。
container
  用於轉譯 reCAPTCHA 小工具的 HTML 元素。指定容器的 ID (字串) 或 DOM 元素本身。
參數
包含鍵/值組合參數的物件，例如 {"sitekey": "your_site_key", "theme": "light"}。請參閱 grecaptcha.render 參數。
inherit
  如果未指定對應的參數，請使用元素上的現有 data-* 屬性。這些參數的優先順序高於屬性。
grecaptcha.execute(
opt_widget_id
) 		透過程式輔助方式叫用 reCAPTCHA 檢查。當隱形 reCAPTCHA 位於 div 時使用 而不是按鈕
opt_widget_id
選用的小工具 ID，如果未指定，則預設為建立的第一個小工具。
grecaptcha.reset(
opt_widget_id
) 		重設 reCAPTCHA 小工具。
opt_widget_id
選用的小工具 ID；如未指定，就會預設為建立的第一個小工具。
grecaptcha.getResponse(
opt_widget_id
) 		取得 reCAPTCHA 小工具的回應。
opt_widget_id
選用的小工具 ID，如果未指定，則預設為建立的第一個小工具。

範例

在 onload 回呼後明確轉譯

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render after an onload callback</title>
    <script>
        var onSubmit = function(token) {
          console.log('success!');
        };

        var onloadCallback = function() {
          grecaptcha.render('submit', {
            'sitekey' : 'your_site_key',
            'callback' : onSubmit
          });
        };
    </script>
  </head>
  <body>
    <form action="?" method="POST">
      <input id="submit" type="submit" value="Submit">
    </form>
    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

在用戶端驗證後叫用隱形 reCAPTCHA 驗證問題。

<html>
  <head>
  <script>
    function onSubmit(token) {
      alert('thanks ' + document.getElementById('field').value);
    }

    function validate(event) {
      event.preventDefault();
      if (!document.getElementById('field').value) {
        alert("You must add text to the required field");
      } else {
        grecaptcha.execute();
      }
    }

    function onload() {
      var element = document.getElementById('submit');
      element.onclick = validate;
    }
  </script>
  <script src="https://www.google.com/recaptcha/api.js" async defer></script>
  </head>
  <body>
    <form>
      Name: (required) <input id="field" name="field">
      <div id="recaptcha" class="g-recaptcha"
          data-sitekey="_your_site_key_"
          data-callback="onSubmit"
          data-size="invisible"></div>
      <button id="submit">submit</button>
    </form>
    <script>onload();</script>
  </body>
</html>