「使用 Google HTML 登入」API 參考資料

此參考網頁說明「使用 Google 帳戶登入」HTML 資料屬性 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 的值並非空白,則略過一次輕觸動作。
data-nonce ID 權杖的隨機字串
data-context One Tap 提示的標題和字詞
data-moment_callback 提示 UI 狀態通知事件監聽器的函式名稱
data-state_cookie_domain 如果您需要在上層網域和子網域中呼叫 One Tap,請將上層網域傳遞至這個屬性,以便使用單一共用 Cookie。
data-ux_mode 「使用 Google 帳戶登入」按鈕的使用者體驗流程
data-allowed_parent_origin 允許嵌入中繼 iframe 的來源。如果有這項屬性, One Tap 會在中繼 iframe 模式下執行。
data-intermediate_iframe_close_callback 在使用者手動關閉 One Tap 時,覆寫預設的中繼 iframe 行為。
data-itp_support 啟用 ITP 瀏覽器上的升級版 One Tap 使用者體驗。
data-login_hint 提供使用者提示,略過帳戶選取程序。
data-hd 依網域限制帳戶選取範圍。
data-use_fedcm_for_prompt 允許瀏覽器控管使用者的登入提示,並調解網站和 Google 之間的登入流程。

屬性類型

以下各節將詳細說明每個屬性的類型和範例。

資料-client_id

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

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

data-auto_prompt

這個屬性可決定是否顯示 One Tap。預設值為 true。這個值為 false 時,系統不會顯示 Google One Tap。詳情請參閱下表:

類型 必要 範例
boolean 選用 data-auto_prompt="true"

data-auto_select

如果只有一個 Google 工作階段核准您的應用程式,此屬性會決定是否要自動傳回 ID 權杖,而不進行任何使用者互動。預設值為 false。詳情請參閱下表:

類型 必要 範例
boolean 選用 data-auto_select="true"

data-login_uri

這個屬性是登入端點的 URI。

這個值必須與您在 API 控制台中設定的 OAuth 2.0 用戶端的其中一個已授權重新導向 URI 完全相符,且必須符合我們的重新導向 URI 驗證規則

如果目前的頁面是登入頁面,則系統會預設省略這個屬性。在這種情況下,系統會將憑證張貼到這個頁面。

如果沒有定義回呼函式,且使用者點選「使用 Google 帳戶登入」或「One Tap」按鈕,或發生自動簽署,系統就會將 ID 權杖憑證回應發布至您的登入端點。

詳情請參閱下表:

類型 選用 範例
網址 預設為目前網頁的 URI 或您指定的值。
在設定 data-ux_mode="popup"data-callback 時忽略。
data-login_uri="https://www.example.com/login"

登入端點必須處理包含 credential 金鑰且主體中具有 ID 權杖值的 POST 要求。

以下是傳送至登入端點的要求範例:

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

credential=ID_TOKEN

資料回呼

此屬性是 JavaScript 函式的名稱,用於處理傳回的 ID 權杖。詳情請參閱下表:

類型 必要 範例
字串 如果不設定 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_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。詳情請參閱下表:

類型 必要 範例
boolean 選用 data-cancel_on_tap_outside="false"

data-prompt_parent_id

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

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

如果指定 Cookie 的值並非空白,則這個屬性會略過一次輕觸動作。詳情請參閱下表:

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

資料 Nonce

這項屬性是 ID 權杖使用的隨機字串,用於防止重送攻擊。詳情請參閱下表:

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

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

資料情境

這個屬性會變更 One Tap 提示中顯示的標題文字及訊息。詳情請參閱下表:

類型 必要 範例
字串 選用 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 在彈出式視窗中執行登入使用者體驗流程。
redirect 對完整頁面重新導向執行登入使用者體驗流程。

data-allowed_parent_origin

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

類型 必要 範例
字串或字串陣列 選用 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" 符合 example2.com 的網域 example1.comexample2.com 和子網域
  • 萬用字元網域的開頭必須為安全的 https:// 配置,因此系統會將 "*.example.com" 視為無效。

data-intermediate_iframe_close_callback

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

data-intermediate_iframe_close_callback 欄位只會在中繼 iframe 模式下生效。這只會影響中繼 iframe 而非 One Tap iframe系統會在叫用回呼前移除 One Tap UI。

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

HTML API 不支援命名空間中的 JavaScript 函式。請改用不含命名空間的全域 JavaScript 函式。例如,請使用 mylibCallback,而非 mylib.callback

資料 itp_支援

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

類型 必要 範例
boolean 選用 data-itp_support="true"

data-login_hint

如果您的應用程式事先知道應登入的使用者,便可向 Google 提供登入提示。成功後,就會略過選取帳戶的步驟。 可接受的值包括電子郵件地址或 ID 權杖 sub 欄位。

詳情請參閱 login_hint 的 OpenID Connect 說明文件。

類型 必要 範例
字串。可以是電子郵件地址或 ID 權杖中的 sub 欄位值。 選用 data-login_hint="elisa.beckett@gmail.com"

Data-Hd

使用者有多個帳戶,且應該只透過 Workspace 帳戶登入時,才會使用它來向 Google 提供網域名稱提示。如果成功,則在帳戶選取期間顯示的使用者帳戶,僅限於提供的網域。萬用字元值:* 只會為使用者提供 Workspace 帳戶,而在選取帳戶期間會排除個人帳戶 (user@gmail.com)。

詳情請參閱 hd 的 OpenID Connect 說明文件。

類型 必要 範例
字串。完整的網域名稱,或 *。 選用 data-hd="*"

data-use_fedcm_for_prompt

允許瀏覽器控管使用者登入提示,並調解網站和 Google 之間的登入流程。預設值為 false。詳情請參閱「遷移至 FedCM」頁面。

類型 必要 範例
boolean 選用 data-use_fedcm_for_prompt="true"

類別為「g_id_signin」的元素

如果您在元素的 class 屬性中加入 g_id_signin,該元素會轉譯為「使用 Google 帳戶登入」按鈕。

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

視覺資料屬性

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

屬性
data-type 按鈕類型:圖示或標準按鈕。
data-theme 按鈕主題。例如 filled_blue 或 filled_black。
data-size 按鈕大小。例如大小。
data-text 按鈕文字。例如「使用 Google 帳戶登入」或「使用 Google 帳戶登入」。
data-shape 按鈕形狀。例如矩形或圓形。
data-logo_alignment Google 標誌對齊方式:靠左或置中。
data-width 按鈕寬度,以像素為單位。
data-locale 按鈕文字會以此屬性設定的語言顯示。
data-click_listener 如已設定,則當使用者點選「使用 Google 帳戶登入」按鈕時,系統會呼叫此函式。

屬性類型

以下各節將詳細說明每個屬性的類型和範例。

資料類型

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

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

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

類型
standard
內含文字或個人化資訊的按鈕。
icon
沒有文字的圖示按鈕。

資料主題

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

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

下表列出可用的主題及相關說明:

主題
outline
使用白色背景的標準按鈕 白色背景的圖示按鈕 搭配白色背景的個人化按鈕
標準按鈕主題。
filled_blue
含有藍色背景的標準按鈕 藍色背景的圖示按鈕 搭配藍色背景的個人化按鈕
藍色的按鈕主題。
filled_black
黑色背景的標準按鈕 黑色背景的圖示按鈕 黑色背景的個人化按鈕
黑色的按鈕主題。

data-size

按鈕大小。預設值為 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 繼續」的標準按鈕 未顯示文字的圖示按鈕
按鈕文字為「Continue with 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"

下表列出可用的對齊方式和相關說明:

logo_alignment
left
標準按鈕,左邊顯示 G 標誌
讓 Google 標誌靠左對齊。
center
標準按鈕,中央有 G 標誌
將 Google 標誌置中對齊。

資料寬度

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

詳情請參閱下表:

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

資料地區

選用設定。使用指定語言代碼顯示按鈕文字。如果沒有,則顯示使用者的 Google 帳戶或瀏覽器設定。載入程式庫時,將 hl 參數和語言代碼加入 src 指令,例如:gsi/client?hl=<iso-639-code>

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

詳情請參閱下表:

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

click_listener

您可以使用 click_listener 屬性定義使用者點選「使用 Google 帳戶登入」按鈕時要呼叫的 JavaScript 函式。

  google.accounts.id.renderButton(document.getElementById("signinDiv"), {
      theme: 'outline',
      size: 'large',
      click_listener: onClickHandler
    });

  
  function onClickHandler(){
    console.log("Sign in with Google button clicked...")
  }
  

在這個範例中,使用者點選「Sign in with Google」按鈕時, 訊息會記錄到控制台。

伺服器端整合

您的伺服器端端點必須處理下列 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"
}

sub 欄位是 Google 帳戶的全域專屬 ID。使用 sub 欄位做為使用者的 ID,因為所有 Google 帳戶均有專屬的 ID,也絕不會重複使用。請勿使用電子郵件地址做為 ID,因為 Google 帳戶可在不同的時間點有多個電子郵件地址。

您可以使用 emailemail_verifiedhd 欄位判斷 Google 是否代管,以及是否為某個電子郵件地址的權威性。在 Google 獲得授權的情況下,使用者會確認為合法帳戶擁有者。

具公信力的案件如下:

  • email@gmail.com 字尾,這是 Gmail 帳戶。
  • email_verified 為 true,且 hd 已設定,則這是 Google Workspace 帳戶。

使用者註冊 Google 帳戶時,不必使用 Gmail 或 Google Workspace。 如果 email 不含 @gmail.com 字尾,但 hd 為非 Google 並非官方,建議採用密碼或其他驗證方法來驗證使用者。email_verified 也可以在 Google 帳戶建立時首次驗證使用者時為 True,但第三方電子郵件帳戶的擁有權可能已改變。

exp 欄位會顯示在伺服器端驗證權杖的到期時間。「使用 Google 帳戶登入」功能取得的 ID 權杖為 1 小時。您必須在到期時間之前驗證權杖請勿使用 exp 管理工作階段。過期的 ID 權杖代表使用者已登出。您的應用程式負責管理使用者的工作階段。

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 的『繼續』按鈕」以選取帳戶,接著在彈出式視窗中按下「確認」按鈕,即可同意授權及分享憑證。適用於非 Chromium 式瀏覽器。
btn 已在現有工作階段中取得同意聲明的使用者,點選「使用 Google 帳戶登入」按鈕,並從「選擇帳戶」中選取 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 如何選取憑證。