「使用 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 的來源。如有這個屬性，則輕觸一下會在中繼 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 Cloud 控制台中找到並建立。詳情請參閱下表：

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

資料自動提示

這項屬性可決定是否要顯示「一次輕觸」手勢。預設值為 true。如果這個值為 false，系統就不會顯示 Google One 感應支付功能。詳情請參閱下表：

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

資料-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"

登入端點必須處理內文中含有 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。詳情請參閱下表：

類型	必要	範例
boolean	選用	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 使用」

資料-回呼

此屬性是提示 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"

data-ux_mode

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

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

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

使用者體驗模式
popup	在彈出式視窗中執行登入使用者體驗流程。
redirect	透過整頁重新導向，執行登入使用者體驗流程。

data-allowed_parent_origin

允許嵌入中繼 iframe 的來源。如果系統顯示這個屬性，則一次輕觸會在中繼 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」按鈕手動關閉 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。

data-itp_support

這個欄位會決定是否要在支援智慧型追蹤 (ITP) 的瀏覽器中，啟用 升級版 One Tap UX。預設值為 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"

資料 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」類別的元素

如果將 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 帳戶登入」按鈕時，系統會呼叫這個函式。
data-state	如果設定，此字串就會傳回 ID 權杖。

屬性類型

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

資料類型

按鈕類型。預設值為 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
signup_with
continue_with
signin

資料形狀

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

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

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

形狀
rectangular
pill
circle
square

資料標誌對齊

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

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

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

logo_alignment
left
center

資料寬度

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

詳情請參閱下表：

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

資料語言代碼

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

如果不設定這項政策，系統會使用瀏覽器的預設語言代碼或 Google 工作階段使用者的偏好設定。因此，不同使用者可能會看到本地化按鈕的不同版本，以及不同的大小。

詳情請參閱下表：

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

data-click_listener

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

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

在此範例中，當使用者按一下「Sign in with Google」按鈕按下... 時，控制台會記錄訊息。

data-state

選用：由於可以在同一個頁面上顯示多個「使用 Google 帳戶登入」按鈕，因此您可以為每個按鈕指派專屬字串。相同的字串會與 ID 符記一併傳回，所以您可以識別使用者點選了哪個按鈕登入。

詳情請參閱下表：

類型	必要	範例
字串	選用	data-state="button 1"

伺服器端整合

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

ID 權杖處理常式端點

ID 權杖處理常式端點會處理 ID 權杖。根據對應帳戶的狀態，您可以登入使用者，並引導他們前往註冊頁面，或引導他們前往帳戶連結頁面以瞭解更多資訊。

HTTP POST 要求包含下列資訊：

形式	名稱	說明
Cookie	g_csrf_token	隨機字串，會隨著每次要求傳送至處理常式端點。
要求參數	g_csrf_token	與先前的 Cookie 值 g_csrf_token 相同的字串。
要求參數	credential	Google 核發的 ID 權杖。
要求參數	select_by	憑證的選取方式。
要求參數	state	只有在使用者點選「使用 Google 帳戶登入」按鈕登入，且已指定按鈕的 state 屬性時，才能定義這個參數。

憑證

解碼後，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，因為 Google 帳戶可在不同時間點使用多個電子郵件地址。

使用 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 並非權威性密碼或其他驗證方法，建議使用以驗證使用者。email_verified 也可能是真實的，因為 Google 最初在建立 Google 帳戶時已完成身分驗證，但是第三方電子郵件帳戶的擁有權可能已經改變。

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

select_by

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

• 使用者已按下 One Tap 或「使用 Google 帳戶登入」按鈕，或使用無接觸自動登入程序。

• 找到現有工作階段，或使用者選取並登入 Google 帳戶，即可建立新工作階段。

• 先向使用者提供 ID 權杖憑證前，

  • 已按下「確認」按鈕，同意他們共用憑證
  • 先前已取得同意，並使用選取帳戶 來選擇 Google 帳戶

這個欄位的值已設為其中一個類型

值	說明
auto	針對先前已同意共用憑證的現有工作階段，自動登入使用者。僅適用於不支援 FedCM 的瀏覽器。
user	現有的工作階段使用者先前已取得同意聲明，按下 One Tap 的「繼續以其他方式繼續」按鈕共用憑證。僅適用於非 FedCM 支援的瀏覽器。
fedcm	使用者已按下 One Tap 的「繼續以其他方式繼續」按鈕，透過 FedCM 共用憑證。僅適用於 FedCM 支援的瀏覽器。
fedcm_auto	針對先前已同意透過 FedCM One Tap 共用憑證的現有工作階段自動登入使用者。僅適用於 FedCM 支援的瀏覽器。
user_1tap	目前有工作階段的使用者按下 One Tap 的「繼續以其他方式繼續」按鈕，藉此表示同意並分享憑證。僅適用於 Chrome 75 以上版本。
user_2tap	沒有現有工作階段的使用者已按下 One Tap 的「Continue as」按鈕選取帳戶，然後在彈出式視窗中按下「確認」按鈕，藉此表示同意並分享憑證。適用於非 Chromium 瀏覽器。
btn	使用者必須取得現有工作階段，且先前已同意「使用 Google 帳戶登入」按鈕，並從「選擇帳戶」中選取 Google 帳戶以共用憑證。
btn_confirm	已有工作階段的使用者按下「使用 Google 帳戶登入」按鈕，然後按下「確認」按鈕以提供同意聲明及分享憑證。
btn_add_session	假如使用者沒有現有工作階段，且先前已取得同意聲明，則已按下「使用 Google 帳戶登入」按鈕選取 Google 帳戶並共用憑證。
btn_confirm_add_session	沒有現有工作階段的使用者，請先按下「使用 Google 帳戶登入」按鈕選取 Google 帳戶，然後按下「確認」按鈕同意並分享憑證。

state

只有在使用者點選「使用 Google 帳戶登入」按鈕登入，且已指定點選按鈕的 data-state 屬性時，才能定義這個參數。這個欄位的值與按鈕 data-state 屬性中指定的值相同。

由於可在同一個頁面上轉譯多個「使用 Google 帳戶登入」按鈕，因此您可以為每個按鈕指派專屬字串。因此，您可以讓這個 state 參數識別使用者點選並登入的按鈕。

密碼憑證處理常式端點

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

HTTP POST 要求包含下列資訊：

形式	名稱	說明
Cookie	g_csrf_token	隨機字串，會隨著每次要求傳送至處理常式端點。
要求參數	g_csrf_token	與先前的 Cookie 值 g_csrf_token 相同的字串。
要求參數	email	Google 核發的 ID 權杖。
要求參數	password	憑證的選取方式。