「使用 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="[e-mail]"

資料 HD 高畫質

當使用者擁有多個帳戶，且只應使用 Workspace 帳戶登入時，可使用此方式向 Google 提供網域名稱提示。如果成功，只有提供的網域才能在帳戶選擇期間顯示使用者帳戶。萬用字元值：* 只會為使用者提供 Workspace 帳戶，而在帳戶選取期間排除個人帳戶 ([e-mail])。

詳情請參閱 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	按鈕文字為「使用 Google 帳戶登入」。
signup_with	按鈕文字為「使用 Google 帳戶註冊」。
continue_with	按鈕文字為「透過 Google 帳戶繼續操作」。
signin	按鈕文字為「登入」。

資料形狀

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

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

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

形狀
rectangular	矩形按鈕。如果是用於 icon 按鈕類型，則與 square 相同。
pill	圓角按鈕。如果是用於 icon 按鈕類型，則與 circle 相同。
circle	圓形按鈕。如果是用於 standard 按鈕類型，則與 pill 相同。
square	正方形按鈕。如果是用於 standard 按鈕類型，則與 rectangular 相同。

資料標誌對齊

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

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

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

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

資料寬度

按鈕寬度的下限 (以像素為單位)。可用的寬度上限為 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": "[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。只限 使用 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	憑證的選取方式。

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