本頁面說明如何在網頁中顯示和自訂 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 資源,即可推斷轉譯。
指定
onload
回呼函式。所有依附元件都載入後,系統就會呼叫此函式。<script type="text/javascript"> var onloadCallback = function() { alert("grecaptcha is ready!"); }; </script>
插入 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>