reCAPTCHA v2

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

若要顯示小工具，您可以：

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

請參閱驗證使用者的回應，檢查使用者是否成功通過人機驗證 (Captcha)。

自動顯示 reCAPTCHA 小工具

如要在網頁上轉譯 reCAPTCHA 小工具，最簡單的方法就是加入必要的 JavaScript 資源與 g-recaptcha 標記。g-recaptcha 標記是 DIV 元素，類別名稱為 g-recaptcha，網站金鑰則位於 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 小工具

指定您的 onback 回呼函式，並新增參數至 JavaScript 資源，即可推斷轉譯。

  1. 指定 onload 回呼函式。所有依附元件都載入後，系統就會呼叫此函式。

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

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

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

    執行回呼時，您可以透過 JavaScript API 呼叫 grecaptcha.render 方法。

設定

JavaScript 資源 (api.js) 參數

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

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

g-recaptcha 標記屬性 grecaptcha.render 參數 值 預設 說明
資料網站金鑰 sitekey 您的網站金鑰。
資料主題 主題 深色光線 燈具 選填欄位，小工具的色彩主題。
資料大小 size 密集 一般 選填欄位，小工具的大小。
data-tabindex 分頁索引 0 選填欄位，小工具的分頁索引和挑戰。如果網頁中有其他元素使用 Tabindex，則應加以設定，讓使用者更容易瀏覽。
資料回呼 回呼 選填欄位，您的回呼函式名稱，會在使用者提交成功的回應時執行。g-recaptcha-response 權杖會傳送到您的回呼。
data-expired-callback 過期回呼 選填欄位，您的回呼函式名稱，會在 reCAPTCHA 回應過期，且使用者必須重新驗證時執行。
資料錯誤-回呼 錯誤回呼 選填欄位，您的回呼函式名稱，當 reCAPTCHA 遇到錯誤 (通常是網路連線) 時執行，在連線恢復之前才能繼續。如果在這裡指定函式，您必須負責通知使用者應重試。

JavaScript API

方法 說明
grecaptcha.render(
容器
參數
)		 將容器轉譯為 reCAPTCHA 小工具，並傳回新建小工具的 ID。
container
顯示 reCAPTCHA 小工具的 HTML 元素。指定容器 (字串) 或 DOM 元素本身的 ID。
parameters
包含參數為鍵值對組合的物件，例如：{"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；如果未指定，則會預設為第一個建立小工具。

範例

載入回呼後進行顯式轉譯

<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>