警告:這項資料是依據《 Google 使用者資料政策》規定提供。請詳閱並遵守相關政策。否則可能會導致專案或帳戶遭到停權。

使用 Google HTML API 登入

此參考資料頁面說明「使用 Google 帳戶登入」資料屬性 API。您可以使用這個 API 在網頁中顯示 One Tap 提示或「使用 Google 帳戶登入」按鈕。

ID 為「g_id_onload」的元素

您可以將「登入 Google」資料屬性放在任何可見或隱藏元素中,例如 <div><span>。唯一的條件是元素 ID 已設為 g_id_onload。請勿將這個 ID 放在多個元素上。

資料屬性

下表列出包含資料說明的資料屬性:

屬性
data-client_id 應用程式的用戶端 ID
data-auto_prompt 顯示 Google One 感應付款功能。
data-auto_select 啟用 Google One Tap 的自動選取功能。
data-login_uri 您的登入端點網址
data-callback JavaScript ID 符記處理常式函式名稱
data-native_login_uri 密碼憑證處理常式端點的網址
data-native_callback JavaScript 密碼憑證處理常式函式名稱
data-native_id_param credential.id 參數的參數名稱
data-native_password_param credential.password 參數的參數名稱
data-cancel_on_tap_outside 控制是否要在使用者點擊提示以外之處,取消提示。
data-prompt_parent_id One Tap 提示容器元素的 DOM ID
data-skip_prompt_cookie 如果指定的 Cookie 含有非空白值,會略過 One Tap。
data-nonce ID 憑證的隨機字串
data-context 「輕觸一下」提示中的標題和字詞
data-moment_callback 提示 UI 狀態通知接聽器的函式名稱
data-state_cookie_domain 如果需要在上層網域及其子網域中呼叫 One Tap,請將上層網域傳送至這項屬性,系統就會使用單一共用 Cookie。
data-ux_mode 「使用 Google 帳戶登入」按鈕 UX 流程
data-allowed_parent_origin 允許嵌入中繼 iframe 的來源。如果這項屬性出現,「One Tap」會在中間 iframe 模式下執行。
data-intermediate_iframe_close_callback 當使用者手動關閉 One Tap 時,會覆寫預設的中繼 iframe 行為。
data-itp_support 在 ITP 瀏覽器中啟用升級後的 One Tap 使用者體驗。

屬性類型

以下各節包含各屬性類型及範例的詳細資料。

data-client_id

這個屬性是應用程式的用戶端 ID,可在 Google Developers Console 中找到並製作。詳情請參閱下表:

類型 需要 範例
字串 data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-auto_prompt

此屬性可決定是否要顯示「輕觸一次」功能。預設值為 true。這個值為 false 時,不會顯示 Google One 觸控功能。詳情請參閱下表:

類型 需要 範例
布林值 選用 data-auto_prompt="true"

資料自動選取

如果只有一個 Google 工作階段已核准您的應用程式,這個屬性可決定是否要在沒有使用者互動的情況下,自動傳回 ID 憑證。預設值為 false。詳情請參閱下表:

類型 需要 範例
布林值 選用 data-auto_select="true"

資料登入

這個屬性是登入端點的 URI。如果目前的網頁是您的登入頁面,系統可能會省略該憑證。在這種情況下,系統會將憑證預設為發布到這個頁面。

如未定義回呼函式,且使用者按一下 [使用 Google 帳戶登入] 或 [輕觸] 按鈕 (或會自動進行登入) 時,系統就會將 ID 憑證憑證回應發布到您的登入端點。

詳情請參閱下表:

類型 選用 範例
網址 預設值為目前網頁的 URI 或您指定的值。
如果設定了 data-ux_mode="popup"data-callback,系統會忽略這個屬性。
data-login_uri="https://www.example.com/login"

您的登入端點必須處理 POST 要求,且內文中必須包含 credential 金鑰和 ID 符記值。

以下是您登入端點的要求範例:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

資料回呼

這個屬性是處理傳回 ID 憑證的 JavaScript 函式名稱。詳情請參閱下表:

類型 需要 範例
字串 如未設定 data-login_uri,則為必要屬性。 data-callback="handleToken"

可能使用 data-login_uridata-callback 屬性之一。這取決於下列元件和使用者體驗模式設定:

  • 目前data-login_uri[登入 Google] 按鈕的必要屬性 redirect使用者體驗模式會略過data-callback屬性。

  • 您必須為 Google One Tap 和 Google 登入按鈕 popup 使用者體驗模式設定這兩個屬性的其中一個。如果同時設定這兩種屬性,則 data-callback 屬性的優先順序較高。

HTML API 不支援命名空間內的 JavaScript 函式。因此,請使用沒有命名空間的全域 JavaScript 函式。例如,請使用 mylibCallback 而非 mylib.callback

資料原生登入

這個屬性是密碼憑證處理常式端點的網址。如果您設定了 data-native_login_uri 屬性或 data-native_callback 屬性,則當沒有 Google 工作階段時,JavaScript 程式庫會恢復為原生憑證管理員。您無法同時設定 data-native_callbackdata-native_login_uri 屬性。詳情請參閱下表:

類型 需要 範例
字串 選用 data-login_uri="https://www.example.com/password_login"

data-native_callback

這個屬性是 JavaScript 函式的名稱,可處理瀏覽器原生憑證管理員傳回的密碼憑證。如果您設定了 data-native_login_uri 屬性或 data-native_callback 屬性,則當沒有 Google 工作階段時,JavaScript 程式庫會恢復為原生憑證管理員。您無法同時設定 data-native_callbackdata-native_login_uri。詳情請參閱下表:

類型 需要 範例
字串 選用 data-native_callback="handlePasswordCredential"

HTML API 不支援命名空間內的 JavaScript 函式。因此,請使用沒有命名空間的全域 JavaScript 函式。例如,請使用 mylibCallback 而非 mylib.callback

data-native_id_param

將密碼憑證提交至密碼憑證處理常式端點時,可以為 credential.id 欄位指定參數名稱。預設名稱為 email。詳情請參閱下表:

類型 需要 範例
網址 選用 data-native_id_param="user_id"

data-native_password_param

將密碼憑證提交至密碼憑證處理常式端點時,可以為 credential.password 值指定參數名稱。預設名稱為「password」。詳情請參閱下表:

類型 需要 範例
網址 選用 data-native_password_param="pwd"

data-cancel_on_tap_outside

這個屬性可設定使用者是否在提示以外點擊時,取消 One Tap 要求。預設值為 true。如要停用此功能,請將值設為 false。詳情請參閱下表:

類型 需要 範例
布林值 選用 data-cancel_on_tap_outside="false"

data-prompt_parent_id

這個屬性可設定容器元素的 DOM ID。如果尚未設定,系統會在視窗右上角顯示 One Tap 提示。詳情請參閱下表:

類型 需要 範例
字串 選用 data-prompt_parent_id="parent_id"

如果指定的 Cookie 含有非空白值,這個屬性會略過 One Tap。詳情請參閱下表:

類型 需要 範例
字串 選用 data-skip_prompt_cookie="SID"

data-nonce

此屬性是 ID 符記用來防止重播攻擊的隨機字串。詳情請參閱下表:

類型 需要 範例
字串 選用 data-nonce="biaqbm70g23"

無長度限制受限於您環境支援的 JWT 大小上限,以及個別瀏覽器和伺服器的 HTTP 大小限制。

資料背景資訊

這項屬性會變更標題文字,以及「輕觸一次」提示中顯示的訊息。詳情請參閱下表:

類型 需要 範例
字串 選用 data-context="use"

下表列出了可用的背景資訊和相關說明:

背景資訊
signin 「使用 Google 帳戶登入」
signup 「註冊 Google」
use 「與 Google 搭配使用」

data-moment_callback

此屬性是提示 UI 狀態通知監聽器的函式名稱。詳情請參閱資料類型 PromptMomentNotification。詳情請參閱下表:

類型 需要 範例
字串 選用 data-moment_callback="logMomentNotification"

HTML API 不支援命名空間內的 JavaScript 函式。因此,請使用沒有命名空間的全域 JavaScript 函式。例如,請使用 mylibCallback 而非 mylib.callback

如果您需要在上層網域及其子網域中顯示 One Tap,請將上層網域傳遞至這項屬性,這樣會使用單一共用狀態 Cookie。詳情請參閱下表:

類型 需要 範例
字串 選用 data-state_cookie_domain="example.com"

data-ux_mode

這個屬性用來設定 [使用 Google 帳戶登入] 按鈕的使用者體驗流程。預設值為 popup。此屬性不會影響 One Tap 使用者體驗。詳情請參閱下表:

類型 需要 範例
字串 選用 data-ux_mode="redirect"

下表列出了可用的使用者體驗模式及其說明。

使用者體驗模式
popup 在彈出式視窗中執行登入 UX 流程。
redirect 執行完整頁面登入,以執行登入使用者體驗流程。

data-allowed_parent_origin

允許嵌入中繼 iframe 的來源。如果有這個屬性,「One Tap 」會在中間的 iframe 模式中執行。詳情請參閱下表:

類型 需要 範例
字串或字串陣列 選用 data-allowed_parent_origin="https://example.com"

下表列出支援的值類型及其說明。

值類型
string 單一網域 URI。 「https://example.com」
string array 以逗號分隔的網域 URI 清單。 "https://news.example.com,https://local.example.com"

如果 data-allowed_parent_origin 屬性值無效,中繼 iframe 模式的 One Tap 初始化作業將會失敗並停止。

此外,您也可以使用萬用字元前置字串。舉例來說,"https://*.example.com" 會比對 example.com 及其所有層級的子網域 (例如 news.example.comlogin.news.example.com)。使用萬用字元時,請注意下列事項:

  • 模式字串不能只使用萬用字元和頂層網域。例如 https://*.comhttps://*.co.uk 無效;如上所述,"https://*.example.com" 會比對 example.com 及其子網域。您也可以用逗號分隔的清單來代表 2 個不同的網域。舉例來說,"https://example1.com,https://*.example2.com" 會比對網域 example1.comexample2.comexample2.com 的子網域
  • 萬用字元網域必須以安全的 https:// 配置做為開頭。系統會將「"*.example.com"」視為無效。

data-中繼_iframe_close_callback

在使用者手動關閉 One Tap 時,輕觸 One Tap 使用者介面中的 [X] 按鈕,覆寫預設的中間 iframe 行為。預設行為是立即從 DOM 移除中繼 iframe。

data-intermediate_iframe_close_callback 欄位只有在中繼 iframe 模式下才會生效。而這只會影響中間的 iframe,而不是「One Tap」的 iframe。系統會先刪除 One Tap 使用者介面,再叫用回呼。

類型 需要 範例
函式 選用 data-intermediate_iframe_close_callback="logBeforeClose"

HTML API 不支援命名空間內的 JavaScript 函式。因此,請使用沒有命名空間的全域 JavaScript 函式。例如,請使用 mylibCallback 而非 mylib.callback

data-itp_support

這個欄位可決定是否要在支援智慧防追蹤功能 (ITP) 的瀏覽器上,啟用 升級版 One Tap 使用者體驗。預設值為 false。詳情請參閱下表:

類型 需要 範例
布林值 選用 data-itp_support="true"

含有「g_id_signin」類別的元素

如果您將 g_id_signin 新增至元素的 class 屬性,該元素會顯示為「使用 Google 帳戶登入」按鈕。

您可以在同一個頁面上顯示多個「使用 Google 帳戶登入」按鈕。每個按鈕都可以有自己的視覺設定。這些設定是由下列資料屬性定義。

視覺資料屬性

下表列出視覺化資料屬性和相關說明:

屬性
data-type 按鈕類型:圖示或標準按鈕。
data-theme 按鈕主題。例如 fill_blue 或 fill_black。
data-size 按鈕大小。例如「小」或「大」。
data-text 按鈕文字。例如「使用 Google 帳戶登入」或「使用 Google 帳戶註冊」。
data-shape 按鈕形狀。例如:矩形或圓形。
data-logo_alignment Google 標誌對齊方式:靠左或置中。
data-width 按鈕寬度 (以像素為單位)。
data-locale 按鈕文字會以此屬性中設定的語言顯示。

屬性類型

以下各節包含各屬性類型及範例的詳細資料。

資料類型

按鈕類型。預設值為 standard。詳情請參閱下表:

類型 需要 範例
字串 data-type="icon"

下表列出可用的按鈕類型及其說明:

類型
standard 包含文字或個人化資訊的按鈕:
icon 不含文字的圖示按鈕:

資料主題

按鈕主題。預設值為 outline。詳情請參閱下表:

類型 需要 範例
字串 選用 data-theme="filled_blue"

下表列出了可用的主題及其說明:

主題
outline 標準按鈕主題:
搭配白色背景的標準按鈕 有白色背景的圖示按鈕 帶有白色背景的個人化按鈕
filled_blue 藍色的按鈕主題:
有藍色背景的標準按鈕 有藍色背景的圖示按鈕 套用藍色背景的個人化按鈕
filled_black 黑色的按鈕主題:
黑色背景搭配標準按鈕 有黑色背景的圖示按鈕 採用黑色背景的個人化按鈕

資料大小

按鈕大小。預設值為 large。詳情請參閱下表:

類型 需要 範例
字串 選用 data-size="small"

下表列出可用的按鈕大小及相關說明。

大小
large 大型按鈕:
大型標準按鈕 大型圖示按鈕 大型的個人化按鈕
medium 中型按鈕:
中型標準按鈕 中型圖示按鈕
small 小按鈕:
小型按鈕 小型圖示按鈕

資料文字

按鈕文字。預設值為 signin_with。具有不同 data-text 屬性的圖示按鈕文字沒有視覺差異。唯一的例外是,如果文字在閱讀過程中為文字無障礙功能,

詳情請參閱下表:

類型 需要 範例
字串 選用 data-text="signup_with"

下表列出可用的按鈕文字和說明:

文字
signin_with 按鈕文字為「使用 Google 帳戶登入」:
標有「使用 Google 帳戶登入」的標準按鈕 沒有可見文字的圖示按鈕
signup_with 按鈕文字為「透過 Google 註冊」:
標示為「使用 Google 帳戶註冊」的標準按鈕 沒有可見文字的圖示按鈕
continue_with 按鈕文字為「透過 Google 帳戶繼續操作」:
標有「透過 Google 帳戶繼續操作」的標準按鈕 沒有可見文字的圖示按鈕
signin 按鈕文字為「登入」:
標示為 [登入] 的標準按鈕 沒有可見文字的圖示按鈕

資料形狀

按鈕形狀。預設值為 rectangular。詳情請參閱下表:

類型 需要 範例
字串 選用 data-shape="rectangular"

下表列出可用的按鈕形狀及其說明:

圖案
rectangular 矩形按鈕。如果用於 icon 按鈕類型,則與 square 相同。
矩形標準按鈕 矩形圖示按鈕 矩形個人化按鈕
pill 膠囊型按鈕。如果用於 icon 按鈕類型,則與 circle 相同。
膠囊型標準按鈕 膠囊圖示圖示 膠囊型個人化按鈕
circle 圓形的按鈕。如果用於 standard 按鈕類型,則與 pill 相同。
圓形標準按鈕 圓形圖示按鈕 圓形個人化按鈕
square 方形按鈕。如果用於 standard 按鈕類型,則與 rectangular 相同。
正方形標準按鈕 正方形圖示按鈕 正方形個人化按鈕

data-logo_alignment

Google 標誌的對齊方式。預設值為 left。這個屬性僅適用於 standard 按鈕類型。詳情請參閱下表:

類型 需要 範例
字串 選用 data-logo_alignment="center"

下表列出各種對齊方式及其說明:

標誌對齊
left 靠左對齊 Google 標誌:
左邊有 G 標誌的標準按鈕
center 置中對齊 Google 標誌:
中間有 G 標誌的標準按鈕

資料寬度

最小按鈕寬度 (以像素為單位)。可用的寬度上限為 400 像素。

詳情請參閱下表:

類型 需要 範例
字串 選用 data-width=400

資料地區

按鈕文字的預設語言代碼。如果未設定,系統會使用瀏覽器的預設語言代碼或 Google 工作階段使用者的偏好設定。因此,不同使用者可能會看見不同版本的本地化按鈕,而且大小可能不同。

詳情請參閱下表:

類型 需要 範例
字串 選用 data-locale="zh_CN"

伺服器端整合

您的伺服器端端點必須處理下列 HTTP POST 要求。

ID 憑證處理常式端點

ID 憑證處理常式端點會處理這個 ID 符記。您可以根據對應的帳戶狀態登入,並將使用者導向至註冊網頁,或是將使用者導向帳戶連結網頁,以取得更多資訊。

HTTP POST 要求包含下列資訊:

格式化 名稱 說明
Cookie g_csrf_token 隨機字串會隨要求傳送至處理常式端點而改變。
要求參數 g_csrf_token 這個字串與先前的 Cookie 值相同,g_csrf_token.
要求參數 credential Google 核發的 ID 憑證。
要求參數 select_by 選擇憑證的方式。

解碼時,ID 憑證看起來會像這樣:

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": "Eliza",
  "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"
}

下表列出 select_by 欄位可能的值。使用按鈕類型搭配工作階段和同意聲明狀態來設定值

  • 使用者已按下 One Tap 或 Google 帳戶登入

  • 已找到現有的工作階段,或者使用者選取並登入 Google 帳戶來建立新的工作階段。

  • 與使用者分享 ID 憑證憑證之前

    • 已按下 [確認] 按鈕,表示同意分享憑證。
    • 先前已同意且使用 [選取帳戶] 來選擇 Google 帳戶

這個欄位的值設為以下其中一種類型:

說明
auto 使用先前已同意分享憑證的現有工作階段,讓使用者自動登入。
user 已有工作階段的使用者先前已獲得同意,且只要點選 [繼續為] 按鈕,即可分享憑證。
user_1tap 已有工作階段的使用者按下 [輕觸操作] 按鈕,表示同意並分享憑證。僅適用於 Chrome 75 以上版本。
user_2tap 沒有現有工作階段的使用者會按一次 [繼續] 適用於非 Chromium 瀏覽器。
btn 已有工作階段的使用者先前已獲得同意,且已按下 [使用 Google 帳戶登入] 按鈕,並選取 [選擇帳戶] 來分享憑證。
btn_confirm 已有工作階段的使用者按下 [使用 Google 帳戶登入] 按鈕並按下 [確認] 按鈕,表示同意並分享憑證。
btn_add_session 沒有先前工作階段的使用者尚未取得同意,請按下 [使用 Google 帳戶登入] 按鈕選取 Google 帳戶並共用憑證。
btn_confirm_add_session 沒有現有工作階段的使用者先按下「使用 Google 帳戶登入」按鈕選取 Google 帳戶,再按下 [確認] 按鈕同意授權並分享憑證。

密碼憑證處理常式端點

密碼憑證處理常式端點會處理原生憑證管理員擷取的密碼憑證。

HTTP POST 要求包含下列資訊:

格式化 名稱 說明
Cookie g_csrf_token 隨機字串會隨要求傳送至處理常式端點而改變。
要求參數 g_csrf_token 這個字串與先前的 Cookie 值 g_csrf_token 相同。
要求參數 email Google 核發的這個 ID 憑證。
要求參數 password 選擇憑證的方式。