reCAPTCHA v2

本頁說明如何在網頁上顯示和自訂 reCAPTCHA v2 小工具。

如要顯示小工具，您可以採取下列任一做法：

如要瞭解如何自訂小工具，請參閱「設定」一節。舉例來說，您可以指定小工具的語言或主題。

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

自動轉譯 reCAPTCHA 小工具

如要在網頁轉譯 reCAPTCHA 小工具，最簡單的方法就是加入 必要的 JavaScript 資源和 g-recaptcha 標記g-recaptcha 標記 是包含 g-recaptcha 類別名稱的 DIV 元素，以及網站金鑰的 data-sitekey 屬性：

<html>
  <head>
    <title>reCAPTCHA demo: Simple page</title>
    <script src="https://www.google.com/recaptcha/api.js" async defer></script>
  </head>
  <body>
    <form action="?" method="POST">
      <div class="g-recaptcha" data-sitekey="your_site_key"></div>
      <br/>
      <input type="submit" value="Submit">
    </form>
  </body>
</html>

指令碼必須使用 HTTPS 通訊協定載入，且可以從任何 不受限。

明確轉譯 reCAPTCHA 小工具

可以指定 onload 回呼函式，即可延後轉譯作業 以及新增參數至 JavaScript 資源

  1. 指定 onload 回呼函式。這個函式會在 所有依附元件都已載入

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

  2. 插入 JavaScript 資源，並將 onload 參數設為名稱 onload 回呼函式和 explicit 的 render 參數。

    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
    async defer>
</script>

    執行回呼時，您可以呼叫 grecaptcha.render 方法 來自 JavaScript API

設定

JavaScript 資源 (api.js) 參數

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

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

g-recaptcha 標記屬性 grecaptcha.render 參數 值 預設 說明
data-sitekey 網站鍵 您的網站金鑰。
data-theme 主題 深淺 燈具 選用設定。小工具的顏色主題。
資料大小 大小 精簡正常 一般 選用設定。小工具的大小。
data-tabindex Tabindex 0 選用設定。小工具和挑戰的分頁索引。如果網頁中的其他元素使用 Tabindex，則應該設定用於方便使用者瀏覽。
data-callback 回呼 選用設定。回呼函式的名稱，會在使用者提交成功回應時執行。g-recaptcha-response 權杖會傳遞至回呼。
data-expired-callback expired-callback 選用設定。回呼函式的名稱，會在 reCAPTCHA 回應到期時執行，讓使用者必須重新驗證。
data-error-callback 錯誤回呼 選用設定。回呼函式的名稱；reCAPTCHA 遇到錯誤時就會執行此函式 (通常是網路連線)，直到連線恢復為止。如果您在這裡指定函式，則需負責通知使用者應重試。

JavaScript API

方法 說明
grecaptcha.render(
容器
parameters
) 		將容器顯示為 reCAPTCHA 小工具，並傳回新建立小工具的 ID。
容器
算繪 reCAPTCHA 小工具的 HTML 元素。指定容器 (字串) 或 DOM 元素本身的 ID。
參數
包含鍵/值組合參數的物件，例如 {"sitekey": "your_site_key", "theme": "light"}。請參閱 grecaptcha.render 參數。
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 type="text/javascript">
      var onloadCallback = function() {
        grecaptcha.render('html_element', {
          'sitekey' : 'your_site_key'
        });
      };
    </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/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

多個小工具的明確顯示

<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.render('example1', {
          'sitekey' : 'your_site_key',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.render(document.getElementById('example2'), {
          'sitekey' : 'your_site_key'
        });
        grecaptcha.render('example3', {
          'sitekey' : 'your_site_key',
          'callback' : verifyCallback,
          'theme' : 'dark'
        });
      };
    </script>
  </head>
  <body>
    <!-- The g-recaptcha-response string displays in an alert message upon submit. -->
    <form action="javascript:alert(grecaptcha.getResponse(widgetId1));">
      <div id="example1"></div>
      <br>
      <input type="submit" value="getResponse">
    </form>
    <br>
    <!-- Resets reCAPTCHA widgetId2 upon submit. -->
    <form action="javascript:grecaptcha.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/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>