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

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

ID 為「g_id_onload」的元素

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

資料屬性

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

屬性類型

以下各節將詳細說明每個屬性的類型和範例。

data-client_id

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

data-auto_prompt

這項屬性會決定是否顯示 One Tap。預設值為 true。這個值為「false」時，系統不會顯示 Google One 輕觸功能。詳情請參閱下表：

data-auto_select

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

data-login_uri

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

這個值必須與 OAuth 2.0 用戶端的其中一個授權重新導向 URI 完全相符，您可以在 API 控制台中設定這類 URI，且必須符合我們的重新導向 URI 驗證規則。

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

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

詳情請參閱下表：

您的登入端點必須處理含有 credential 鍵的 POST 要求，且要求主體中必須含有 ID 權杖值。

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

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

data-callback

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

可能會使用 data-login_uri 和 data-callback 其中一個屬性。取決於下列元件和 UX 模式設定：

• data-login_uri 屬性是「使用 Google 帳戶登入」按鈕 redirect UX 模式的必要屬性，該模式會忽略 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。詳情請參閱下表：

data-nonce

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

Nonce 長度會受到環境支援的 JWT 大小上限，以及個別瀏覽器和伺服器 HTTP 大小限制的限制。

資料情境

這個屬性會變更 One Tap 提示中顯示的標題文字和訊息。詳情請參閱下表：

下表列出所有可用上下文及其說明：

data-moment_callback

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

詳情請參閱下表：

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

data-state_cookie_domain

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

data-ux_模式

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

下表列出可用的 UX 模式及其說明。

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 及其子網域。您也可以使用以半形逗號分隔的清單，代表 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。

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

data-itp_support

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

資料登入提示

如果應用程式事先知道應登入哪位使用者，就能向 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-enable_redirect_uri_validation

啟用符合重新導向 URI 驗證規則的按鈕重新導向流程。

含有「g_id_signin」類別的元素

如果您將 g_id_signin 新增至元素的 class 屬性，元素會顯示為「Sign In With Google」按鈕。

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

視覺資料屬性

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

屬性類型

以下各節將詳細說明每個屬性的類型和範例。

data-type

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

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

類型
standard
icon

data-theme

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

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

主題
outline
filled_blue
filled_black

data-size

按鈕大小。預設值為 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

資料寬度

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

詳情請參閱下表：

data-locale

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

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

詳情請參閱下表：

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>

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

data-state

選用：由於同一個網頁上可以顯示多個「使用 Google 帳戶登入」按鈕，您可以為每個按鈕指派專屬字串。系統會將相同的字串與 ID 權杖一併傳回，方便您判斷使用者點選哪個按鈕登入。

詳情請參閱下表：

伺服器端整合

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

ID 權杖處理常式端點

ID 權杖處理程序端點會處理 ID 權杖。根據對應帳戶的狀態，您可以讓使用者登入，並將他們導向註冊頁面或帳戶連結頁面，以便取得更多資訊。

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 帳戶中均不重複，且絕不會重複使用。請勿使用電子郵件地址做為 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 權杖並「不」代表使用者已登出。應用程式會負責使用者的工作階段管理。

select_by

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

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

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

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

  • 按下「確認」按鈕以表示同意共用憑證
  • 先前已同意並使用「選取帳戶」功能選擇 Google 帳戶。

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

州

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

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

密碼憑證處理程序端點

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

HTTP POST 要求包含以下資訊：