此參考資料頁面說明 Sign-In JavaScript API。您可以使用這個 API 在網頁中顯示 One Tap 提示或「使用 Google 帳戶登入」按鈕。
方法：google.accounts.id.初始化
google.accounts.id.initialize 方法會根據設定物件來初始化「使用 Google 帳戶登入」用戶端。以下的程式碼範例範例如下：
google.accounts.id.initialize(IdConfiguration)
下列程式碼範例使用 onload 函式實作 google.accounts.id.initialize 方法：
<script>
window.onload = function () {
google.accounts.id.initialize({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: handleCredentialResponse
});
google.accounts.id.prompt();
};
</script>
資料類型：IdConfiguration
下表列出 IdConfiguration 資料類型的欄位與說明：
| 欄位 | |
|---|---|
client_id |
您應用程式的用戶端 ID |
auto_select |
啟用自動選取功能。 |
callback |
處理 ID 憑證的 JavaScript 函式。Google One Tap 和「使用 Google 帳戶登入」按鈕 popup 使用者體驗模式會使用這項屬性。 |
login_uri |
您的登入端點網址。「使用 Google 帳戶登入」按鈕 redirect
使用者體驗模式會使用這項屬性。 |
native_callback |
處理密碼憑證的 JavaScript 函式。 |
cancel_on_tap_outside |
如果使用者點選提示之外的位置，取消提示。 |
prompt_parent_id |
One Tap 提示容器元素的 DOM ID |
nonce |
ID 憑證的隨機字串 |
context |
「輕觸一下」提示中的標題和字詞 |
state_cookie_domain |
如果需要在上層網域及其子網域上呼叫 One Tap，請將上層網域傳送至這個欄位，系統就會使用單一共用 Cookie。 |
ux_mode |
「使用 Google 帳戶登入」按鈕 UX 流程 |
allowed_parent_origin |
允許嵌入中繼 iframe 的來源。如果顯示這個欄位，「One Tap」就會在中間的 iframe 模式中執行。 |
intermediate_iframe_close_callback |
當使用者手動關閉 One Tap 時，會覆寫預設的中繼 iframe 行為。 |
itp_support |
在 ITP 瀏覽器中啟用升級後的 One Tap 使用者體驗。 |
client_id
這個欄位是應用程式的用戶端 ID，可在 Google Developers Console 中找到及建立。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 是 | client_id: "CLIENT_ID.apps.googleusercontent.com" |
自動選取
這個欄位可決定當以前只已核准一個 Google 工作階段時，該 ID 憑證是否會自動傳回使用者沒有任何互動。預設值為 false。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 布林值 | 選用 | auto_select: true |
callback
這個欄位是 JavaScript 函式來處理從 One Tap 提示或彈出式視窗傳回的 ID 憑證。如果您使用 Google One Tap 或「使用 Google 帳戶登入」按鈕 popup 使用者體驗模式，就必須設定這個屬性。
詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| function | One Tap 功能和 popup 使用者體驗模式的必要項目 |
callback: handleResponse |
login_uri
這個屬性是登入端點的 URI。如果目前的網頁是您的登入頁面，系統可能會省略該憑證。在這種情況下，系統會將憑證預設為發布到這個頁面。
當使用者使用「使用 Google 帳戶登入」按鈕及重新導向 UX 模式時，系統會將 ID 憑證憑證回應發布到您的登入端點。
詳情請參閱下表：
| 類型 | 選用 | 範例 |
|---|---|---|
| 網址 | 預設值為目前網頁的 URI 或您指定的值。 只有在已設定 ux_mode: "redirect" 時才使用。 |
login_uri="https://www.example.com/login" |
您的登入端點必須處理含有「credential」金鑰的 POST 要求，且該主體中須包含 ID 憑證值。
以下是您登入端點的要求範例：
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
credential=ID_TOKEN
native_callback
這個欄位是 JavaScript 函式的名稱，可處理從瀏覽器原生憑證管理員傳回的密碼憑證。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| function | 選用 | native_callback: handleResponse |
un_on_tap_outside
這個欄位設定是否要在使用者點擊提示後，取消 One Tap 要求。預設值為 true。如果您將值設為 false，即可將其停用。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 布林值 | 選用 | cancel_on_tap_outside: false |
提示_上層 ID
這個屬性可設定容器元素的 DOM ID。如果未設定該提示，視窗視窗右上角會顯示「One Tap 提示」。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | prompt_parent_id: 'parent_id' |
Nonce
這個欄位是 ID 權杖用來避免重複進行攻擊的隨機字串。 詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | nonce: "biaqbm70g23" |
無長度限制受限於您環境支援的 JWT 大小上限，以及個別瀏覽器和伺服器的 HTTP 大小限制。
context
這個欄位會變更「輕觸一次」提示訊息的標題和訊息。 詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | context: "use" |
下表列出了可用的背景資訊和相關說明：
| 背景資訊 | |
|---|---|
signin |
「使用 Google 帳戶登入」 |
signup |
「立即註冊 Google」 |
use |
「與 Google 搭配使用」 |
State_cookie_domain
如果您需要在上層網域及其子網域中顯示 One Tap，請將上層網域傳送至這個欄位，讓系統使用單一共用狀態 Cookie。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | state_cookie_domain: "example.com" |
ux_mode
您可以使用這個欄位來設定「使用 Google 帳戶登入」按鈕的使用者體驗流程。預設值為 popup。這個屬性對 OneTap UX 沒有影響。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | ux_mode: "redirect" |
下表列出了可用的使用者體驗模式及其說明。
| 使用者體驗模式 | |
|---|---|
popup |
在彈出式視窗中執行登入 UX 流程。 |
redirect |
執行完整網頁重新導向，執行登入使用者體驗流程。 |
允許父項來源
允許嵌入中繼 iframe 的來源。如果其中有「Tap Tap」，就會以中間 iframe 模式執行。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串或字串陣列 | 選用 | allowed_parent_origin: "https://example.com" |
下表列出支援的值類型及其說明。
| 值類型 | ||
|---|---|---|
string |
單一網域 URI。 | https://example.com" |
string array |
網域 URI 陣列。 | [https://news.example.com", "https://local.example.com"] |
此外，您也可以使用萬用字元前置字串。舉例來說，"https://*.example.com" 會比對所有層級的 example.com 及其子網域 (例如 news.example.com、login.news.example.com)。使用萬用字元時請注意下列事項：
- 模式字串不能只使用萬用字元和頂層網域。舉例來說，
https://*.com和https://*.co.uk無效；如上所述，"https://*.example.com"會比對example.com及其子網域。您也可以使用陣列來代表 2 個不同的網域。舉例來說，["https://example1.com", "https://*.example2.com"]會比對網域example1.com、example2.com與example2.com的子網域 - 萬用字元網域必須以安全的 https:// 配置做為開頭。系統會將「
"*.example.com"」視為無效。
如果 allowed_parent_origin 欄位的值無效，則中繼 iFrame 模式的 One Tap 初始化作業將會失敗並停止。
中繼_iframe_關閉_回呼
當使用者手動關閉 One Tap 的 One Tap UI 時，輕觸「#39;X'」按鈕即可覆寫預設的中間 iframe 行為。預設行為是立即從 DOM 移除中繼 iframe。
intermediate_iframe_close_callback 欄位只有在中繼 iframe 模式下才會生效。而這只會影響中間的 iframe，而不是「One Tap」的 iframe。系統會先刪除 One Tap 使用者介面，再叫用回呼。
| 類型 | 必要 | 範例 |
|---|---|---|
| function | 選用 | intermediate_iframe_close_callback: logBeforeClose |
itp_support
這個欄位可決定是否要在支援智慧防追蹤功能 (ITP) 的瀏覽器上，啟用升級版 One Tap 使用者體驗。預設值為 false。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 布林值 | 選用 | itp_support: true |
方法：google.accounts.id.prompt
google.accounts.id.prompt 方法會在叫用 initialize() 方法後顯示 One Tap 提示或瀏覽器原生憑證管理員。以下的程式碼範例範例如下：
google.accounts.id.prompt(/**
@type{(function(!PromptMomentNotification):void)=} */ momentListener)
一般來說，網頁載入時就會呼叫 prompt() 方法。基於 Google 端的工作階段狀態和使用者設定，系統可能不會顯示「One Tap 提示」使用者介面。如要在不同時刻收到使用者介面狀態的通知，請傳送函式以接收 UI 狀態通知。
系統會在下列時間觸發通知：
- 顯示時刻：系統會在呼叫
prompt()方法之後發生。通知內含一個布林值，表示使用者介面是否顯示。 已略過：當 One Tap 提示遭到自動取消、手動取消，或 Google 無法核發憑證 (例如所選工作階段登出 Google) 時，就會發生這種錯誤。
在這類情況下，建議您繼續前往下一個識別資訊提供者 (如果有的話)。
已關閉的時刻：如果 Google 成功擷取憑證，或是使用者想要停止憑證擷取流程，就會發生這種情形。例如，當使用者開始在登入對話方塊中輸入使用者名稱和密碼時，您可以呼叫
google.accounts.id.cancel()方法來關閉 One Tap 提示並觸發關閉的時刻。
以下的程式碼範例會實作略過的時刻：
<script>
window.onload = function () {
google.accounts.id.initialize(...);
google.accounts.id.prompt((notification) => {
if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
// continue with another identity provider.
}
});
};
</script>
資料類型：PromptMomentNotification
下表列出 PromptMomentNotification 資料類型的方法和說明：
| 方法 | |
|---|---|
isDisplayMoment() |
這則通知是要顯示「顯示時間」嗎？ |
isDisplayed() |
是否顯示螢幕通知，並顯示使用者介面？ |
isNotDisplayed() |
這則通知是否為顯示時間，卻不會顯示使用者介面？ |
getNotDisplayedReason() |
無法顯示使用者介面的詳細原因。可能的值如下：
|
isSkippedMoment() |
這則通知是關於略過片段嗎？ |
getSkippedReason() |
略過片段的詳細原因。可能的值如下：
|
isDismissedMoment() |
這則通知是關於已關閉的時刻嗎？ |
getDismissedReason() |
關閉的原因。可能的值如下：
|
getMomentType() |
傳回時刻類型的字串。可能的值如下：
|
資料類型：CredentialResponse
叫用 callback 函式時，系統會傳送 CredentialResponse 物件做為參數。下表列出憑證回應物件中包含的欄位：
| 欄位 | |
|---|---|
credential |
這個欄位是傳回的 ID 憑證。 |
select_by |
這個欄位可設定憑證的選取方式。 |
憑證
這個欄位是採用 Base64 編碼的 JSON Web Token (JWT) 字串的 ID 憑證。
解碼時，JWT 看起來會像這樣：
header
{
"alg": "RS256",
"kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
"typ": "JWT"
}
payload
{
"iss": "https://accounts.google.com", // The JWT's issuer
"nbf": 161803398874,
"aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
"sub": "3141592653589793238", // The unique ID of the user's Google Account
"hd": "gmail.com", // If present, the host domain of the user's GSuite email address
"email": "elisa.g.beckett@gmail.com", // The user's email address
"email_verified": true, // true, if Google has verified the email address
"azp": "314159265-pi.apps.googleusercontent.com",
"name": "Elisa Beckett",
// If present, a URL to user's profile picture
"picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
"given_name": "Elisa",
"family_name": "Beckett",
"iat": 1596474000, // Unix timestamp of the assertion's creation time
"exp": 1596477600, // Unix timestamp of the assertion's expiration time
"jti": "abc161803398874def"
}
sub 欄位包含 Google 帳戶的全域唯一識別碼。
您可以使用 email、email_verified 和 hd 欄位來判斷 Google 是否託管及擁有電子郵件地址的權威性。如果 Google 具有權威性，目前已知的使用者是合法帳戶擁有者。
在下列情況下，Google 將視為具公信力的案例：
- 「
email」的後置字串為@gmail.com，這是 Gmail 帳戶。 email_verified是 true，hd已設定，這是 G Suite 帳戶。
使用者可以註冊 Google 帳戶，而不使用 Gmail 或 G Suite。當 email 不包含 @gmail.com 後置字串，而 hd 不存在時，Google 不會產生權威性，因此建議您使用密碼或其他驗證方式來驗證使用者。email_verfied 也可能為真，因為 Google 最初在建立 Google 帳戶時驗證了使用者，但第三方電子郵件帳戶的擁有權可能已經改變。
select_by
下表列出 select_by 欄位可能的值。使用按鈕類型搭配工作階段和同意聲明狀態來設定值
使用者已按下 One Tap 或「使用 Google 登入」按鈕，或使用觸控式自動登入程序
已找到現有的工作階段，或者使用者選取並登入 Google 帳戶來建立新的工作階段。
與使用者分享 ID 憑證憑證之前，
- 已按下 [確認] 按鈕，表示同意分享憑證。
- 先前已同意且使用 [選取帳戶] 來選擇 Google 帳戶
這個欄位的值設為以下其中一種類型：
| 值 | 說明 |
|---|---|
auto |
使用先前已同意共用憑證的現有工作階段，讓使用者自動登入。 |
user |
已有工作階段的使用者先前已同意同意聲明 會輕觸 One Tap 'Continue as' 按鈕以共用憑證。 |
user_1tap |
已有現有工作階段的使用者會按下 One Tap 'Continue as' 按鈕，表示同意並分享憑證。僅適用於 Chrome 75 以上版本。 |
user_2tap |
沒有現有工作階段的使用者會按下 One Tap 'Continue as' 按鈕以選取帳戶，接著在彈出式視窗中按下 [Confirm] (確認) 按鈕，表示同意並分享憑證。適用於非 Chromium 瀏覽器。 |
btn |
已有工作階段的使用者，先前已同意 [以 Google 登入] 按鈕，然後從「'選擇帳戶'」選取 Google 帳戶以共用憑證。 |
btn_confirm |
已有工作階段的使用者按下 [使用 Google 帳戶登入] 按鈕並按下 [確認] 按鈕，表示同意並分享憑證。 |
btn_add_session |
沒有先前工作階段的使用者尚未取得同意，請按下 [使用 Google 帳戶登入] 按鈕選取 Google 帳戶並共用憑證。 |
btn_confirm_add_session |
沒有現有工作階段的使用者先按下「使用 Google 帳戶登入」按鈕選取 Google 帳戶，再按下 [確認] 按鈕同意授權並分享憑證。 |
方法：google.accounts.id.renderButton
google.accounts.id.renderButton 方法會在您的網頁中顯示「使用 Google 帳戶登入」按鈕。
以下的程式碼範例範例如下：
google.accounts.id.renderButton(
/** @type{!HTMLElement} */ parent,
/** @type{!GsiButtonConfiguration} */ options
)
資料類型：GsiButtonConfiguration
下表列出 GsiButtonConfiguration 資料類型的欄位與說明：
| 屬性 | |
|---|---|
type |
按鈕類型：圖示或標準按鈕。 |
theme |
按鈕主題。例如 fill_blue 或 fill_black。 |
size |
按鈕大小。例如「小」或「大」。 |
text |
按鈕文字。例如「使用 Google 帳戶登入」或「使用 Google 帳戶註冊」。 |
shape |
按鈕形狀。例如：矩形或圓形。 |
logo_alignment |
Google 標誌對齊方式：靠左或置中。 |
width |
按鈕寬度 (以像素為單位)。 |
locale |
如果設定了，則會顯示按鈕語言。 |
屬性類型
以下各節將詳細說明各個屬性類型和範例。
類型
按鈕類型。預設值為 standard。
詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 是 | type: "icon" |
下表列出可用的按鈕類型及其說明：
| 類型 | |
|---|---|
standard |
包含文字或個人化資訊的按鈕：
|
icon |
不含文字的圖示按鈕： |
主題
按鈕主題。預設值為 outline。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | theme: "filled_blue" |
下表列出了可用的主題及相關說明：
| 主題 | |
|---|---|
outline |
標準按鈕主題：
|
filled_blue |
藍色的按鈕主題：
|
filled_black |
黑色的按鈕主題：
|
大小
按鈕大小。預設值為 large。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | size: "small" |
下表列出可用的按鈕大小及相關說明：
| 大小 | |
|---|---|
large |
大型按鈕：
|
medium |
中型按鈕：  |
small |
小按鈕：
|
傳簡訊給
按鈕文字。預設值為 signin_with。具有不同 text 屬性的圖示按鈕文字沒有視覺差異。唯一的例外是，當文字在螢幕畫面上閱讀時，就適合在螢幕畫面上閱讀。
詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | text: "signup_with" |
下表列出可用的按鈕文字和說明：
| 文字 | |
|---|---|
signin_with |
按鈕文字為「使用 Google 帳戶登入」：
|
signup_with |
按鈕文字是「透過 Google 註冊」：
|
continue_with |
按鈕文字為「透過 Google 帳戶繼續操作」： |
signin |
按鈕文字為「登入」：
|
shape
按鈕形狀。預設值為 rectangular。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | shape: "rectangular" |
下表列出可用的按鈕形狀及其說明：
| 圖案 | |
|---|---|
rectangular |
矩形按鈕。如果用於 icon 按鈕類型，則它與 square 相同。
|
pill |
膠囊型按鈕。如果用於 icon 按鈕類型，則它與 circle 相同。
|
circle |
圓形的按鈕。如果用於 standard 按鈕類型，它會與 pill 相同。
|
square |
方形按鈕。如果用於 standard 按鈕類型，它會與 rectangular 相同。
|
標誌對齊
Google 標誌的對齊方式。預設值為 left。這個屬性僅適用於 standard 按鈕類型。詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | logo_alignment: "center" |
下表列出各種對齊方式及其說明：
| 標誌對齊 | |
|---|---|
left |
靠左對齊 Google 標誌。
|
center |
置中對齊 Google 標誌。
|
寬度
最小按鈕寬度 (以像素為單位)。寬度上限為 400 像素。
詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | width: 400 |
語言代碼
按鈕文字的預設語言代碼。如未設定，系統會使用瀏覽器的預設語言代碼或 Google 工作階段使用者的偏好設定。因此，不同使用者可能會看見不同版本的本地化按鈕，而且大小可能不同。
詳情請參閱下表：
| 類型 | 必要 | 範例 |
|---|---|---|
| 字串 | 選用 | locale: "zh_CN" |
資料類型：憑證
叫用 native_callback 函式時，系統會傳送 Credential 物件做為參數。下表列出物件所含欄位：
| 欄位 | |
|---|---|
id |
識別使用者。 |
password |
密碼 |
方法：google.accounts.id.disableAutoSelect
當使用者登出您的網站時，您必須呼叫 google.accounts.id.disableAutoSelect 方法在 Cookie 中記錄狀態。避免 UX 故障循環。此方法的程式碼片段如下：
google.accounts.id.disableAutoSelect()
下列程式碼範例使用 onSignout() 函式實作 google.accounts.id.disableAutoSelect 方法：
<script>
function onSignout() {
google.accounts.id.disableAutoSelect();
}
</script>
方法：google.accounts.id.storeCredential
此方法是簡易瀏覽器包裝函式，適用於瀏覽器原生憑證管理員 API 的 store() 方法。因此，這只能用來儲存密碼憑證。以下的程式碼範例範例如下：
google.accounts.id.storeCredential(Credential, callback)
下列程式碼範例使用 onSignIn() 函式實作 google.accounts.id.storeCredential 方法：
<script>
function onSignIn() {
let cred = {id: '...', password: '...'};
google.accounts.id.storeCredential(cred);
}
</script>
方法：google.accounts.id.cancel
如果您從依賴方 DOM 中移除提示，可以取消 One Tap 流程。如已選取憑證，則系統會忽略取消作業。請參閱下列程式碼範例：
google.accounts.id.cancel()
下列程式碼範例使用 onNextButtonClicked() 函式實作 google.accounts.id.cancel() 方法：
<script>
function onNextButtonClicked() {
google.accounts.id.cancel();
showPasswordPage();
}
</script>
程式庫載入回呼：onGoogleLibraryLoad
您可以註冊 onGoogleLibraryLoad 回呼。載入「使用 Google JavaScript 登入」程式庫載入後，系統會發出通知：
window.onGoogleLibraryLoad = () => {
...
};
這個回呼只是 window.onload 回呼的捷徑。這種行為不會有任何差異。
下列程式碼範例會導入 onGoogleLibraryLoad 回呼：
<script>
window.onGoogleLibraryLoad = () => {
google.accounts.id.initialize({
...
});
google.accounts.id.prompt();
};
</script>
方法：google.accounts.id.revoke
google.accounts.id.revoke 方法會撤銷用於為指定使用者共用 ID 憑證的 OAuth 授權。請參閱下列方法的程式碼片段：google.accounts.id.revoke(hint, callback)
| 參數 | 類型 | 說明 |
|---|---|---|
hint |
字串 | 使用者 Google 帳戶的電子郵件地址或專屬 ID。ID 是 credential 酬載的 sub 屬性。 |
callback |
function | 選用的 RevocationResponse 處理常式。 |
下列程式碼範例示範如何將 revoke 方法與 ID 搭配使用。
google.accounts.id.revoke('1618033988749895', done => {
console.log(done.error);
});
資料類型：RevocationResponse
叫用 callback 函式時，系統會傳送 RevocationResponse 物件做為參數。下表列出撤銷回應物件所含的欄位：
| 欄位 | |
|---|---|
successful |
這個欄位是方法呼叫的傳回值。 |
error |
這個欄位會包含詳細的錯誤回應訊息。 |
成功
如果撤銷方法呼叫成功或失敗，這個欄位會設為一個布林值。
錯誤
此欄位是字串值，如果撤銷方法呼叫失敗時，包含詳細錯誤訊息，則在成功時不會定義。