使用 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 含有非空白值，請略過 One Tap。
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 使用者體驗。

屬性類型

以下各節提供每個屬性類型及範例的詳細資料。

資料用戶端 ID

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

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

資料自動提示

這項屬性可決定是否要顯示 One Tap。預設值為 true。這個值為 false 時，不會顯示 Google One 感應。詳情請參閱下表：

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

資料自動選取

如果這個屬性只有一個 Google 工作階段已核准您的應用程式，這個屬性可指出是否自動傳回 ID 權杖，無需任何使用者互動。預設值為 false。詳情請參閱下表：

類型	必要	範例
布林值	選用	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"

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

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

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_uri 和 data-callback 屬性。取決於下列元件和使用者體驗模式設定：

• 「登入 Google」按鈕 redirect 使用者體驗模式需要 data-login_uri 屬性，該屬性會忽略 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_callback 和 data-native_login_uri 屬性。詳情請參閱下表：

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

資料原生回呼

這個屬性是 JavaScript 函式的名稱，可處理瀏覽器原生憑證管理員傳回的密碼憑證。如果設定了 data-native_login_uri 屬性或 data-native_callback 屬性，沒有 Google 工作階段時，JavaScript 程式庫就會改回使用原生憑證管理員。您無法同時設定 data-native_callback 和 data-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"

data-skip_prompt_cookie

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

類型	必要	範例
字串	選用	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。

data-state_cookie_domain

如果您需要在上層網域及其子網域中顯示 One Tap，請將上層網域傳遞到這項屬性，讓系統使用單一共用狀態 Cookie。詳情請參閱下表：

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

資料模式

這項屬性可以設定「使用 Google 帳戶登入」按鈕採用的使用者體驗流程。預設值為 popup。這項屬性對 One Tap 使用者體驗沒有任何影響。詳情請參閱下表：

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

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

使用者體驗模式
popup	在彈出式視窗中執行登入使用者體驗流程。
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.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" 會視為無效。

data-intermediate_iframe_close_callback

當使用者輕觸 One Tap UI 中的「X」按鈕時，覆寫預設的中繼 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。

data-itp_support

此欄位是用來判斷是否應在支援智慧追蹤 (ITP) 的瀏覽器上啟用 升級的 One Tap 使用者體驗。預設值為 false。詳情請參閱下表：

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

含有「g_id_signin」類別的元素

如果您將 g_id_signin 新增至元素的 class 屬性，該元素就會顯示為「使用 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	黑色按鈕按鈕：

資料大小

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

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

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

大小
large	大型按鈕：
medium	中型按鈕：
small	小型按鈕：

資料文字

按鈕文字。預設值為 signin_with。不同 data-text 屬性的圖示按鈕文字沒有視覺差異。唯一的例外是文字可供螢幕閱讀，

詳情請參閱下表：

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

下表列出可用按鈕的文字和相關說明：

文字
signin_with	按鈕的文字是「使用 Google 帳戶登入」：
signup_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"

下表列出可用的對齊方式及相關說明：

標誌對齊
left	將 Google 標誌靠左對齊：
center	置中對齊 Google 標誌：

資料寬度

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

詳情請參閱下表：

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

資料語言代碼

選用設定。使用指定語言代碼顯示按鈕文字，否則會預設為使用者的 Google 帳戶或瀏覽器設定。載入程式庫時，將 hl 參數和語言代碼新增至 src 指令，例如：gsi/client?hl=<iso-639-code>。

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

詳情請參閱下表：

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

點擊播放清單

您可以使用 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」按鈕時，系統會記錄「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": "[e-mail]", // 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。

使用 email、email_verified 和 hd 欄位，您可以判斷 Google 是否代管電子郵件地址，以及該來源是否具有電子郵件地址授權。如果 Google 已授權使用者為正當帳戶擁有者，

具有 Google 權威性的情況：

• email 有 @gmail.com 後置字串，也就是 Gmail 帳戶。
• email_verified 為 true，而 hd 已設定為 Google Workspace 帳戶。

使用者可以在沒有使用 Gmail 或 Google Workspace 的情況下註冊 Google 帳戶。如果 email 不含 @gmail.com 後置字串，且 hd 缺少 Google，則 Google 並非正式授權，也不要使用密碼或其他驗證方式來驗證使用者。email_verfied 也是 Google 最初建立 Google 帳戶時驗證使用者的帳戶，但第三方電子郵件帳戶的擁有權可能已變更。

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

select_by

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

• 使用者按下了「一鍵輕觸」或「使用 Google 帳戶登入」按鈕，或使用觸控式自動登入程序。

• 系統偵測到現有工作階段，或使用者選取並登入 Google 帳戶來建立新的工作階段。

• 先與應用程式使用者分享 ID 權杖憑證，

  • 按下「確認」按鈕，同意同意分享憑證；或
  • 之前已提供同意聲明，且使用「選取帳戶」來選擇 Google 帳戶。

這個欄位的值設為下列其中一種類型：

值	說明
auto	自動登入使用者先前已完成同意分享憑證的工作階段。
user	如果現有工作階段的使用者已同意授予同意聲明，按下 One Tap 的 [繼續為] 按鈕即可分享憑證。
user_1tap	現有工作階段的使用者按一下了「繼續輕觸」按鈕，表示同意並分享憑證。僅適用於 Chrome v75 以上版本。
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	憑證的選取方式。

注意： 您可以使用資料屬性變更 email 和 password 參數名稱。