本頁面由 Cloud Translation API 翻譯而成。

隱形 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 中顯示驗證方式，並以程式輔助方式呼叫執行。

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

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

從 JavaScript 方法呼叫 grecaptcha.execute。
```
grecaptcha.execute();
```
執行回呼後，您可以從 JavaScript API 呼叫 grecaptcha.render 方法。
您必須在 reCAPTCHA API 載入前定義 onload 回呼函式。如何確保沒有競爭狀況：
- 先處理回呼，再進行 reCAPTCHA
- 在 `script` 標記中使用 `async` 和 `defer` 參數

設定

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>