本頁面說明如何在網頁上啟用及自訂隱形 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
方法。
設定
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(
|
透過程式輔助方式叫用 reCAPTCHA 檢查。當隱形 reCAPTCHA 位於 div 時使用
而不是按鈕opt_widget_id 選用的小工具 ID,如果未指定,則預設為建立的第一個小工具。 |
grecaptcha.reset(
|
重設 reCAPTCHA 小工具。opt_widget_id 選用的小工具 ID;如未指定,就會預設為建立的第一個小工具。 |
grecaptcha.getResponse(
|
取得 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>