使用 Google 登入 HTML API 參考資料

本參考頁面說明「使用 Google 帳戶登入」HTML 資料屬性 API，可用於在網頁上顯示「使用 Google 帳戶登入」按鈕或 One Tap 提示。

ID 為「g_id_onload」的元素

您可以將「使用 Google 帳戶登入」資料屬性放在任何可見或隱藏的元素中，例如 <div> 和 <span>。唯一的要求是將元素 ID 設為 g_id_onload。請勿將這個 ID 放在多個元素上。

資料屬性

下表列出資料屬性及其說明：

屬性類型

下列各節詳細說明每個屬性類型，並提供範例。

data-client_id

這個屬性是應用程式的用戶端 ID，可在 Google Cloud 控制台中找到並建立。詳情請參閱下表：

data-color_scheme

這個欄位是套用至「One Tap」提示的色彩配置。詳情請參閱下表：

下表列出可用的配色主題及其說明。

data-auto_prompt

這項屬性會決定是否顯示「一鍵登入」。預設值為 true。如果這個值是 false，就不會顯示 Google One 輕觸。詳情請參閱下表：

data-auto_select

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

data-login_uri

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

這個值必須與 Google Auth Platform 中設定的 OAuth 2.0 用戶端其中一個已授權重新導向 URI 完全相符，且必須符合重新導向 URI 驗證規則。

如果目前頁面是登入頁面，則可省略這項屬性，因為系統預設會將憑證發布至這個頁面。

如果未定義回呼函式，且使用者點選「使用 Google 帳戶登入」或「One Tap」按鈕，或系統自動登入，ID 權杖憑證回應就會發布至登入端點。

您的登入端點必須處理 POST 要求，其中包含主體中的 credential 參數和 ID 權杖值。

詳情請參閱下表：

data-callback

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

可以使用 data-login_uri 和 data-callback 屬性。這取決於下列元件和 UX 模式設定：

• 「使用 Google 帳戶登入」按鈕 redirect UX 模式需要 data-login_uri 屬性，並會忽略 data-callback 屬性。

• 您必須為 Google One Tap 和 Google 登入按鈕 popup UX 模式設定這兩個屬性的其中之一。如果兩者都已設定，data-callback 屬性的優先順序較高。

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

data-native_login_uri

這個屬性是密碼憑證處理常式端點的網址。如果您設定 data-native_login_uri 屬性或 data-native_callback 屬性，JavaScript 程式庫會在沒有 Google 工作階段時，改用內建的憑證管理工具。你無法同時設定「data-native_callback」和「data-native_login_uri」屬性。詳情請參閱下表：

data-native_callback

這個屬性是 JavaScript 函式的名稱，負責處理瀏覽器內建憑證管理工具傳回的密碼憑證。如果您設定 data-native_login_uri 屬性或 data-native_callback 屬性，JavaScript 程式庫會在沒有 Google 工作階段時，改用內建的憑證管理工具。您不得同時設定 data-native_callback 和 data-native_login_uri。詳情請參閱下表：

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

data-native_id_param

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

data-native_password_param

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

data-cancel_on_tap_outside

這項屬性會設定使用者點選提示以外的區域時，是否要取消 One Tap 要求。預設值為 true。如要停用，請將值設為 false。詳情請參閱下表：

data-prompt_parent_id

這項屬性會設定容器元素的 DOM ID。如果未設定，系統會在視窗右上角顯示「One Tap」提示。詳情請參閱下表：

data-skip_prompt_cookie

使用 Cookie 控制 One Tap 提示的顯示方式。如果這項屬性指定的 Cookie 具有非空白值，系統就不會顯示提示。詳情請參閱下表：

data-nonce

這項屬性是 ID 權杖使用的隨機字串，可防止重播攻擊。詳情請參閱下表：

隨機碼長度不得超過環境支援的 JWT 大小上限，以及個別瀏覽器和伺服器的 HTTP 大小限制。

data-essential_claims

這個屬性是字串，用於要求在 Google 傳回的 ID 權杖中加入其他聲明。如需 Google 接受的聲明完整清單，請參閱支援的聲明。

詳情請參閱下表：

data-context

這個欄位會變更「一鍵登入」提示中顯示的標題和訊息文字，但不會影響 ITP 瀏覽器。預設值為 signin。

詳情請參閱下表：

下表列出所有可用的環境和說明：

data-moment_callback

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

詳情請參閱下表：

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

data-state_cookie_domain

如要在上層網域及其子網域中顯示「One Tap」，請將上層網域傳遞至這個屬性，以便使用單一共用狀態 Cookie。詳情請參閱下表：

data-ux_mode

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

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

data-allowed_parent_origin

允許嵌入中繼 iframe 的來源。如果這個���性存在，One Tap 會以中繼 iframe 模式執行。詳情請參閱下表：

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

如果 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 和所有子網域。使用以半形逗號分隔的清單來代表兩個不同的網域。舉例來說，"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 使用者介面。

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

data-itp_support

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

data-login_hint

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

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

data-hd

如果使用者有多個帳戶，但只能透過 Workspace 帳戶登入，請使用這項功能向 Google 提供網域名稱提示。成功後，帳戶選取畫面中顯示的使用者帳戶會僅限於提供的網域。萬用字元值：僅向使用者提供 Workspace 帳戶，並在選取帳戶時排除消費者帳戶 (user@gmail.com)。*

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

data-use_fedcm_for_prompt

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

data-use_fedcm_for_button

這個欄位會決定 Chrome (桌機 M125 以上版本和 Android M128 以上版本) 是否應使用 FedCM 按鈕 UX。預設值為 false。詳情請參閱下表：

data-button_auto_select

這個欄位會決定是否要為 FedCM 按鈕流程啟用「自動選取」選項。啟用後，具有有效 Google 工作階段的回訪者將會自動登入，略過帳戶選擇工具提示。預設為 false。您需要在選擇加入啟動期間明確啟用按鈕自動登入功能。詳情請參閱下表：

類別為「g_id_signin」的元素

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

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

視覺資料屬性

下表列出視覺資料屬性及其說明：

屬性類型

以下各節會詳細說明每個屬性的類型，並提供範例。

資料類型

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

下表列出所有可用的按鈕類型及其說明：

類型
standard
icon

data-theme

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

下表列出可用的主題和說明：

主題	範例	規格
outline		填滿：#FFFFFF 筆觸：#747775 | 1 像素 | 內側 字型：#1F1F1F | Roboto Medium | 14/20 個人化：#1F1F1F | Roboto | Medium 12/14 | Regular 11/13
filled_blue		填滿：#0B57D0 筆觸：#OB57D0 | 1 像素 | 內側 字型：#FFFFFF | Google Sans Medium | 14/20 個人化：#FFFFFF | Roboto | Medium 12/14 | Regular 11/13
filled_black		填滿：#202124 筆觸：#OB57D0 | 1 像素 | 內側 字型：#FFFFFF | Google Sans Medium | 14/20 個人化：#FFFFFF | Roboto | Medium 12/14 | Regular 11/13
outline_dark		填滿：#131314 筆觸：#8E918F | 1 像素 | 內側 字型：#FFFFFF | Google Sans Medium | 14/20 個人化：#FFFFFF | Roboto | Medium 12/14 | Regular 11/13

資料大小

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

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

大小
large
medium
small

data-text

按鈕文字。預設值為 signin_with。如果圖示按鈕的 data-text 屬性不同，文字在視覺上不會有差異。唯一的例外是為螢幕輔助功能讀取文字。

詳情請參閱下表：

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

文字
signin_with
signup_with
continue_with
signin

data-shape

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

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

圖案
rectangular
pill
circle
square

data-logo_alignment

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

下表列出可用的對齊方式和說明：

logo_alignment
left
center

data-width

按鈕寬度下限 (像素)。寬度上限為 400 像素。

詳情請參閱下表：

data-locale

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

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

詳情請參閱下表：

data-click_listener

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

  <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>

在本範例中，當點選「使用 Google 帳戶登入」按鈕時，系統會將「Sign in with Google button clicked...」訊息記錄到控制台。

data-state

(選用) 由於同一個頁面可以顯示多個「使用 Google 帳戶登入」按鈕，您可以為每個按鈕指派專屬字串。這個字串會與 ID 權杖一併傳回，因此您可以識別使用者點選哪個按鈕登入。

詳情請參閱下表：

伺服器端整合

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

ID 權杖處理常式端點

ID 權杖處理常式端點會處理 ID 權杖。根據相應帳戶的狀態，您可以讓使用者登入，並將他們導向註冊頁面或帳戶連結頁面，以取得其他資訊。用戶端「必須」忽略無法辨識的回應參數。

登入端點的要求範例：

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com

credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>

HTTP POST 要求包含下列資訊：

憑證

解碼後，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 Google Workspace email address
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "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 creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

用戶端「必須」忽略無法辨識的 JWT 聲明。

sub 欄位是 Google 帳戶的全域專屬 ID。請只使用 sub 欄位做為使用者 ID，因為這個欄位在所有 Google 帳戶中都是專��的，且絕不會重複使用。

使用 email、email_verified 和 hd 欄位，即可判斷 Google 是否代管電子郵件地址，以及是否為該地址的授權來源。如果 Google 是權威機構，系統會確認使用者是合法帳戶擁有者。

Google 具有權威性的情況：

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

使用者可以註冊 Google 帳戶，不必使用 Gmail 或 Google Workspace。 如果 email 不含 @gmail.com 後置字元，且沒有 hd，Google 就不是授權機構，建議使用密碼或其他驗證方法來驗證使用者。email_verified也可能成立，因為 Google 最初是在建立 Google 帳戶時驗證使用者，但第三方電子郵件帳戶的擁有權可能已變更。

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

g_csrf_token

防偽狀態權杖。這是由 gsi/client 程式庫建立的跨網站要求偽造 (CSRF) 權杖。隨機值會同時以 Cookie 和要求參數的形式，納入 POST 酬載主體。如果在伺服器上處理要求時，這兩個值不相符，則應將要求視為無效。

select_by

下表列出 select_by 欄位的可能值。系統會根據使用的按鈕類型、工作階段和同意聲明狀態，設定值。

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

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

• 在與應用程式分享 ID 權杖憑證之前，使用者必須

  • 按下「確認」按鈕，同意分享憑證，或
  • 先前已授予同意聲明，並使用「選取帳戶」選擇 Google 帳戶。

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

州

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

由於同一個網頁上可以顯示多個「使用 Google 帳戶登入」按鈕，您可以為每個按鈕指派專屬字串。因此，您可以使用這個 state 參數，判斷使用者點選哪個按鈕登入。

密碼憑證處理常式端點

密碼憑證處理常式端點會處理內建憑證管理工具擷取的密碼憑證。

HTTP POST 要求包含下列資訊：