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

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

ID 為「g_id_onload」的元素

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

資料屬性

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

屬性類型

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

data-client_id

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

data-color_scheme

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

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

data-auto_prompt

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

data-auto_select

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

data-login_uri

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

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

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

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

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

詳情請參閱下表：

data-callback

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

系統可能會使用 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

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

data-prompt_parent_id

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

data-skip_prompt_cookie

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

data-nonce

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

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

data-context

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

詳情請參閱下表：

下表列出所有可用環境及其說明：

data-moment_callback

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

詳情請參閱下表：

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

data-state_cookie_domain

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

data-ux_mode

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

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

data-allowed_parent_origin

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

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

如果 data-allowed_parent_origin 屬性的值無效，中繼 iframe 模式的「一鍵登入」初始化作業就會失敗並停止。

也支援萬用字元前置字元。舉例來說，"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，不會影響「一鍵登入」iframe。回呼叫用前，系統會移除「一鍵登入」使用者介面。

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

data-itp_support

這個欄位會決定是否要在支援智慧追蹤預防 (ITP) 功能的瀏覽器上，啟用 升級版一鍵登入使用者體驗。預設值為 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
filled_blue
filled_black

資料大小

按鈕大小。預設值為 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 帳戶或瀏覽器設定。載入程式庫時，請在 src 指令中加入 hl 參數和語言代碼，例如：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 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 帳戶中都是專屬的，且不會重複使用。

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

Google 具有權威性的情況：

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

使用者可以註冊 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 要求包含下列資訊：