Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Sign in with Google JavaScript API 參考資料

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

方法：google.accounts.id.initialize

google.accounts.id.initialize 方法會根據設定物件，初始化「使用 Google 帳戶登入」用戶端。請參閱下列方法的程式碼範例：

google.accounts.id.initialize(IdConfiguration)

下列程式碼範例使用 onload 函式實作 google.accounts.id.initialize 方法：

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

google.accounts.id.initialize 方法會建立「使用 Google 帳戶登入」用戶端執行個體，可由同一網頁中的所有模組隱含使用。

即使您在同一個網頁中使用多個模組 (例如一鍵登入、個人化按鈕、撤銷等)，也只需要呼叫 google.accounts.id.initialize 方法一次。
如果多次呼叫 google.accounts.id.initialize 方法，系統只會記住並使用最後一次呼叫的設定。

每當您呼叫 google.accounts.id.initialize 方法時，系統就會重設設定，且同一網頁中的所有後續方法都會立即使用新設定。

資料類型：IdConfiguration

下表列出 IdConfiguration 資料類型的欄位和說明：

欄位
`client_id`	應用程式的用戶端 ID
`color_scheme`	One Tap 提示套用的色彩配置。
`auto_select`	啟用自動選取功能。
`callback`	處理 ID 權杖的 JavaScript 函式。Google One Tap 和「使用 Google 帳戶登入」按鈕 `popup` UX 模式會使用這個屬性。
`login_uri`	登入端點的網址。「使用 Google 帳戶登入」按鈕 `redirect` UX 模式會使用這個屬性。
`native_callback`	處理密碼憑證的 JavaScript 函式。
`cancel_on_tap_outside`	如果使用者點選提示以外的區域，系統會取消提示。
`prompt_parent_id`	一鍵登入提示容器元素的 DOM ID
`nonce`	ID 權杖的隨機字串
`essential_claims`	要納入 Google 傳回的 ID 權杖中的其他要求。
`context`	One Tap 提示中的標題和文字
`state_cookie_domain`	如需在上層網域及其子網域中呼叫 One Tap，請將上層網域傳遞至這個欄位，以便使用單一共用 Cookie。
`ux_mode`	「使用 Google 帳戶登入」按鈕使用者體驗流程
`allowed_parent_origin`	允許嵌入中繼 iframe 的來源。如果這個欄位存在，一鍵登入功能會在中繼 iframe 模式下執行。
`intermediate_iframe_close_callback`	覆寫使用者手動關閉一鍵登入時，預設的中繼 iframe 行為。
`itp_support`	在 ITP 瀏覽器上啟用升級版一鍵登入使用者體驗。
`login_hint`	提供使用者提示，略過帳戶選取步驟。
`hd`	依網域限制帳戶選取。
`use_fedcm_for_prompt`	已淘汰：此屬性已淘汰，如果使用，系統會忽略。允許瀏覽器控制使用者登入提示，並在網站和 Google 之間協調登入流程。
`use_fedcm_for_button`	這個欄位會決定是否要在 Chrome (電腦版 M125 以上版本和 Android 版 M128 以上版本) 使用 FedCM 按鈕使用者體驗。預設值為 `false`。
`button_auto_select`	是否為 FedCM 按鈕流程啟用自動選取選項。如果啟用，系統會自動登入具有有效 Google 工作階段的回訪者，略過帳戶選擇工具提示。預設值為 `false`。

client_id

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

類型	必填	範例
字串	是	`client_id: "CLIENT_ID.apps.googleusercontent.com"`

color_scheme

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

類型	必填	範例
字串	(選用步驟) 預設為使用者系統的預設色彩配置。	`color_scheme: "dark"`

下表列出可用的色彩配置和說明。

色彩配置
`default`	根據使用者偏好設定，套用使用者系統的預設色彩配置 (淺色或深色)。
`light`	套用淺色色彩配置。
`dark`	套用深色色彩配置。

auto_select

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

類型	必填	範例
布林值	選用	`auto_select: true`

callback

這個欄位是 JavaScript 函式，用於處理從 One Tap 提示或彈出式視窗傳回的 ID 權杖。如果使用 Google One Tap 或「使用 Google 帳戶登入」按鈕 popup UX 模式，則必須提供這項屬性。詳情請參閱下表：

類型	必填	範例
函式	一鍵登入和 `popup` UX 模式的必要條件	`callback: handleResponse`

login_uri

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

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

如果目前網頁是登入網頁，則可省略這個屬性，在這種情況下，憑證預設會發布至這個網頁。

當使用者點選「使用 Google 帳戶登入」按鈕，且使用重新導向使用者體驗模式時，系統會將 ID 權杖憑證回應發布至登入端點。

詳情請參閱下表：

類型	選用	範例
網址	預設為目前網頁的 URI，或您指定的值。只有在設定 `ux_mode: "redirect"` 時才會使用。	`login_uri: "https://www.example.com/login"`

您的登入端點必須處理 POST 要求，其中包含 credential 參數，且主體中含有 ID 權杖值。select_by 不會包含在傳送至 login_uri 或 data-login_uri 的 HTTP POST 要求中，且只會在傳遞至 JavaScript callback 函式的 CredentialResponse 物件中傳回。

native_callback

這個欄位是 JavaScript 函式的名稱，用於處理瀏覽器內建 Credential Manager 傳回的密碼憑證。詳情請參閱下表：

類型	必填	範例
函式	選用	`native_callback: handleResponse`

cancel_on_tap_outside

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

類型	必填	範例
布林值	選用	`cancel_on_tap_outside: false`

prompt_parent_id

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

類型	必填	範例
字串	選用	`prompt_parent_id: 'parent_id'`

Nonce

這個欄位是 ID 權杖使用的隨機字串，用來防範重送攻擊。詳情請參閱下表：

類型	必填	範例
字串	選用	`nonce: "biaqbm70g23"`

Nonce 長度上限取決於環境支援的最大 JWT 大小，以及個別瀏覽器和伺服器的 HTTP 大小限制。

essential_claims

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

詳情請參閱下表：

類型	必填	範例
字串	選用	`essential_claims: "auth_time, amr"`

背景資訊

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

詳情請參閱下表：

類型	必填	範例
字串	選用	`context: "use"`

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

背景資訊
`signin`	「登入」
`signup`	「註冊」
`use`	「使用」

state_cookie_domain

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

類型	必填	範例
字串	選用	`state_cookie_domain: "example.com"`

ux_mode

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

類型	必填	範例
字串	選用	`ux_mode: "redirect"`

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

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

allowed_parent_origin

允許嵌入中繼 iframe 的來源。如果這個欄位存在，一鍵登入功能會在中繼 iframe 模式下執行。詳情請參閱下表：

類型	必填	範例
字串或字串陣列	選用	`allowed_parent_origin: "https://example.com"`

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

值類型
`string`	單一網域 URI。	`"https://example.com"`
`string array`	網域 URI 陣列。	`["https://news.example.com", "https://local.example.com"]`

也支援萬用字元前置字串。舉例來說，"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" 視為無效。

如果 allowed_parent_origin 欄位的值無效，中繼 iframe 模式的一鍵初始化作業會失敗並停止。

intermediate_iframe_close_callback

當使用者輕觸一鍵登入 UI 中的「X」按鈕，手動關閉一鍵登入時，覆寫預設的中繼 iframe 行為。預設行為是立即從 DOM 中移除中介 iframe。

intermediate_iframe_close_callback 欄位僅在中繼 iframe 模式下生效。而且只會影響中介 iframe，不會影響一鍵登入 iframe。系統會在叫用回呼前移除一鍵登入 UI。

類型	必填	範例
函式	選用	`intermediate_iframe_close_callback: logBeforeClose`

itp_support

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

類型	必填	範例
布林值	選用	`itp_support: false`

login_hint

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

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

類型	必填	範例
字串、電子郵件地址或 ID 權杖 `sub` 欄位的值。	選用	`login_hint: 'elisa.beckett@gmail.com'`

HD 高畫質

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

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

類型	必填	範例
字串。完整網域名稱或 *。	選用	`hd: '*'`

use_fedcm_for_prompt

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

類型	必填	範例
布林值	已淘汰	`use_fedcm_for_prompt: true`

use_fedcm_for_button

這個欄位會決定是否要在 Chrome (電腦版 M125 以上版本和 Android M128 以上版本) 使用 FedCM 按鈕使用者體驗。預設值為 false。詳情請參閱下表：

類型	必填	範例
布林值	選用	`use_fedcm_for_button: true`

button_auto_select

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

類型	必填	範例
布林值	選用	`button_auto_select: true`

方法：google.accounts.id.prompt

google.accounts.id.prompt 方法會在叫用 initialize() 方法後，顯示一鍵登入提示或瀏覽器內建的 Credential Manager。請參閱下列方法程式碼範例：

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

一般來說，系統會在載入網頁時呼叫 prompt() 方法。由於 Google 端的階段狀態和使用者設定，系統可能不會顯示一鍵登入提示 UI。如要接收不同時刻的 UI 狀態通知，請傳遞函式來接收 UI 狀態通知。

系統會在下列時間點觸發通知：

顯示時間點：呼叫 prompt() 方法後，通知包含布林值，指出是否顯示 UI。
略過時刻：當一鍵登入提示因自動取消、手動取消而關閉，或 Google 無法核發憑證 (例如所選工作階段已登出 Google) 時，就會發生這種情況。

在這種情況下，建議您繼續前往下一個識別資訊提供者 (如有)。
關閉時刻：當 Google 成功擷取憑證，或使用者想停止憑證擷取流程時，就會發生這種情況。舉例來說，當使用者開始在登入對話方塊中輸入使用者名稱和密碼時，您可以呼叫 google.accounts.id.cancel() 方法關閉一鍵登入提示，並觸發關閉事件。

警告：在關閉時刻，請勿嘗試任何後續的身分識別提供者。

下列程式碼範例會實作略過時刻：

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

資料類型：PromptMomentNotification

下表列出 PromptMomentNotification 資料類型的方法和說明：

方法
`isDisplayMoment()`	如果顯示 One Tap 提示，則傳回 `true`。注意：啟用 FedCM 時，系統不支援這項通知。詳情請參閱「遷移至 FedCM」頁面。
`isDisplayed()`	如果時刻類型為 `PromptMoment.DISPLAY`，且系統顯示一鍵登入提示，則傳回 `true`。注意：啟用 FedCM 時，系統不支援這項通知。詳情請參閱「遷移至 FedCM」頁面。
`isNotDisplayed()`	如果 Moment 類型為 `PromptMoment.DISPLAY`，且未顯示一鍵登入提示，則傳回 `true`。注意：啟用 FedCM 時，系統不支援這項通知。詳情請參閱「遷移至 FedCM」頁面。
`getNotDisplayedReason()`	未顯示 UI 的詳細原因。可能的值如下： `browser_not_supported` `invalid_client` `missing_client_id` `opt_out_or_no_session` `secure_http_required` `suppressed_by_user` `unregistered_origin` `unknown_reason` 注意：啟用 FedCM 時，系統不支援這項通知。詳情請參閱「遷移至 FedCM」頁面。
`isSkippedMoment()`	如果時刻類型為 `PromptMoment.SKIPPED` ，則傳回 `true`。注意：啟用 FedCM 時，系統會部分支援這個方法。尤其是略過原因 `user_cancel`。詳情請參閱「遷移至 FedCM」頁面。
`getSkippedReason()`	略過時刻的詳細原因。可能的值如下： `auto_cancel` `user_cancel` `tap_outside` `issuing_failed` 注意：啟用 FedCM 時，系統會部分支援這個方法。尤其是，不支援 `user_cancel` 的略過原因。詳情請參閱「遷移至 FedCM」頁面。
`isDismissedMoment()`	如果時刻類型為 `PromptMoment.DISMISSED`，則傳回 `true`。注意：啟用 FedCM 後，系統會完全支援這個方法。詳情請參閱「遷移至 FedCM」頁面。
`getDismissedReason()`	駁回的詳細原因。可能的值如下： `credential_returned` `cancel_called` `flow_restarted` 注意：啟用 FedCM 後，系統會完整支援這個方法。詳情請參閱「遷移至 FedCM」頁面。
`getMomentType()`	傳回時刻類型的字串。可能的值如下： `display` `skipped` `dismissed`

資料類型：CredentialResponse

叫用 callback 函式時，系統會將 CredentialResponse 物件做為參數傳遞。下表列出憑證回應物件包含的欄位：

欄位
`credential`	Google 核發的編碼 JWT ID 權杖。
`select_by`	使用者登入的方式。
`state`	只有在使用者點選「使用 Google 帳戶登入」按鈕登入，且已指定按鈕的 `state` 屬性時，系統才會定義這個欄位。

憑證

這個欄位是 ID 權杖，採用 base64 編碼的 JSON Web Token (JWT) 字串。

解碼後，JWT 會如下所示：

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": "Elisa",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

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_verfied 也可能為 true，因為 Google 最初在建立 Google 帳戶時已驗證使用者，但第三方電子郵件帳戶的擁有權可能已變更。

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

select_by

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

使用者按下「一鍵登入」或「使用 Google 帳戶登入」按鈕，或使用免觸控自動登入程序。
系統找到現有工作階段，或使用者選取並登入 Google 帳戶，建立新的工作階段。
使用者必須先完成下列任一操作，系統才會將 ID 權杖憑證提供給應用程式：
- 按下「確認」按鈕，同意分享憑證，或
- 先前已授予同意聲明，並使用「選取帳戶」選擇 Google 帳戶。

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

值	說明
`auto`	自動登入先前已同意分享憑證的使用者，並建立工作階段。僅適用於不支援 FedCM 的瀏覽器。
`user`	使用者已有工作階段，且先前已授予同意聲明，按下一鍵快捷登入「繼續」按鈕，分享憑證。僅適用於不支援 FedCM 的瀏覽器。
`fedcm`	使用者按下「一觸即登」的「繼續」按鈕，透過 FedCM 分享憑證。僅適用於支援 FedCM 的瀏覽器。
`fedcm_auto`	自動登入具有現有工作階段的使用者，且該使用者先前已同意使用 FedCM One Tap 分享憑證。僅適用於支援 FedCM 的瀏覽器。
`user_1tap`	已有工作階段的使用者按下 One Tap「以...身分繼續」按鈕，表示同意並分享憑證。僅適用於 Chrome 75 以上版本。
`user_2tap`	使用者在沒有現有工作階段的情況下，按下 One Tap 的「以...身分繼續」按鈕選取帳戶，然後在彈出式視窗中按下「確認」按鈕，表示同意並分享憑證。適用於非 Chromium 架構的瀏覽器。
`itp`	先前已授予同意聲明的使用者在 ITP 瀏覽器上按下「一鍵登入」。
`itp_confirm`	未授予同意聲明的使用者在 ITP 瀏覽器上按下「一鍵登入」，然後按下「繼續」按鈕，授予同意聲明並分享憑證。
`btn`	先前已授予同意聲明的使用者按下「使用 Google 帳戶登入」按鈕，並從「選擇帳戶」中選取 Google 帳戶，以便分享憑證。
`btn_confirm`	未授權的使用者按下「使用 Google 帳戶登入」按鈕，然後按下「繼續」按鈕，授權並分享憑證。

州

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

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

方法：google.accounts.id.renderButton

google.accounts.id.renderButton 方法會在網頁中顯示「使用 Google 帳戶登入」按鈕。

請參閱下列方法程式碼範例：

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

資料類型：GsiButtonConfiguration

下表列出 GsiButtonConfiguration 資料類型的欄位和說明：

屬性
`type`	按鈕類型：圖示或標準按鈕。
`theme`	按鈕主題。例如 filled_blue 或 filled_black。
`size`	按鈕大小。例如：小或大。
`text`	按鈕文字。例如「使用 Google 帳戶登入」或「使用 Google 帳戶註冊」。
`shape`	按鈕形狀。例如矩形或圓形。
`logo_alignment`	Google 標誌對齊方式：靠左或置中。
`width`	按鈕寬度 (以像素為單位)。
`locale`	如果設定，則會顯示按鈕語言。
`click_listener`	如果設定了這個函式，系統會在使用者點選「使用 Google 帳戶登入」按鈕時呼叫該函式。
`state`	如果設定，這個字串會與 ID 權杖一起傳回。

屬性類型

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

類型

按鈕類型。預設值為 standard。

詳情請參閱下表：

類型	必填	範例
字串	是	`type: "icon"`

下表列出可用的按鈕類型和說明：

類型
`standard`	含有文字或個人化資訊的按鈕。
`icon`	沒有文字的圖示按鈕。

主題

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

類型	必填	範例
字串	選用	`theme: "filled_blue"`

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

主題	範例	規格
`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 \| 1px \| 內側字型：#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。詳情請參閱下表：

類型	必填	範例
字串	選用	`size: "small"`

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

大小
`large`	大型按鈕。
`medium`	中型按鈕。
`small`	小型按鈕。

文字

按鈕文字。預設值為 signin_with。具有不同 text 屬性的圖示按鈕文字，在視覺上沒有差異。唯一的例外是螢幕無障礙功能朗讀文字。

詳情請參閱下表：

類型	必填	範例
字串	選用	`text: "signup_with"`

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

文字
`signin_with`	按鈕文字為「使用 Google 帳戶登入」。
`signup_with`	按鈕文字為「使用 Google 帳戶註冊」。
`continue_with`	按鈕文字為「使用 Google 帳戶繼續」。
`signin`	按鈕文字為「登入」。

形狀

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

類型	必填	範例
字串	選用	`shape: "rectangular"`

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

圖案
`rectangular`	矩形按鈕。如果用於 `icon` 按鈕類型，則與 `square` 相同。
`pill`	藥丸形按鈕。如果用於 `icon` 按鈕類型，則與 `circle` 相同。
`circle`	圓形按鈕。如果用於 `standard` 按鈕類型，則與 `pill` 相同。
`square`	正方形按鈕。如果用於 `standard` 按鈕類型，則與 `rectangular` 相同。

logo_alignment

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

類型	必填	範例
字串	選用	`logo_alignment: "center"`

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

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

寬度

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

詳情請參閱下表：

類型	必填	範例
字串	選用	`width: "400"`

語言代碼

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

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

詳情請參閱下表：

類型	必填	範例
字串	選用	`locale: "zh_CN"`

click_listener

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

  google.accounts.id.renderButton(document.getElementById("signinDiv"), {
      theme: 'outline',
      size: 'large',
      click_listener: onClickHandler
    });

  
  function onClickHandler(){
    console.log("Sign in with Google button clicked...")
  }

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

州

選用：由於同一個頁面可以顯示多個「使用 Google 帳戶登入」按鈕，因此您可以為每個按鈕指派專屬字串。系統會傳回相同的字串和 ID 權杖，方便您識別使用者點選了哪個按鈕登入。

詳情請參閱下表：

類型	必填	範例
字串	選用	`data-state: "button 1"`

資料類型：憑證

叫用 native_callback 函式時，系統會將 Credential 物件做為參數傳遞。下表列出物件包含的欄位：

欄位
`id`	識別使用者。
`password`	密碼

方法：google.accounts.id.disableAutoSelect

使用者登出網站時，您需要呼叫 google.accounts.id.disableAutoSelect 方法，將狀態記錄在 Cookie 中。這可避免使用者體驗陷入死迴圈。請參閱下列方法的程式碼片段：

google.accounts.id.disableAutoSelect()

下列程式碼範例使用 onSignout() 函式實作 google.accounts.id.disableAutoSelect 方法：

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

方法：google.accounts.id.storeCredential

這個方法是瀏覽器內建 Credential Manager API 的 store() 方法包裝函式。因此，只能用於儲存密碼憑證。請參閱下列方法程式碼範例：

google.accounts.id.storeCredential(Credential, callback)

下列程式碼範例使用 onSignIn() 函式實作 google.accounts.id.storeCredential 方法：

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

方法：google.accounts.id.cancel

如果從依賴方 DOM 移除提示，即可取消一鍵登入流程。如果已選取憑證，系統會忽略取消作業。請參閱下列方法程式碼範例：

google.accounts.id.cancel()

下列程式碼範例使用 onNextButtonClicked() 函式實作 google.accounts.id.cancel() 方法：

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

程式庫載入回呼：onGoogleLibraryLoad

您可以註冊 onGoogleLibraryLoad 回呼。載入「使用 Google 帳戶登入」JavaScript 程式庫後，系統會收到通知：

window.onGoogleLibraryLoad = () => {
    ...
};

這個回呼只是 window.onload 回呼的捷徑。行為上沒有任何差異。

下列程式碼範例會實作 onGoogleLibraryLoad 回呼：

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

方法：google.accounts.id.revoke

google.accounts.id.revoke 方法會撤銷用於共用指定使用者 ID 權杖的 OAuth 授權。請參閱下列方法程式碼片段： javascript google.accounts.id.revoke(login_hint, callback)

參數	類型	說明
`login_hint`	字串	使用者 Google 帳戶的電子郵件地址或專屬 ID。ID 是憑證酬載的 `sub` 屬性。
`callback`	函式	選用的 RevocationResponse 處理常式。

以下程式碼範例說明如何搭配 ID 使用 revoke 方法。

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

資料類型：RevocationResponse

叫用 callback 函式時，系統會將 RevocationResponse 物件做為參數傳遞。下表列出撤銷回應物件包含的欄位：

欄位
`successful`	這個欄位是方法呼叫的回傳值。
`error`	這個欄位可包含詳細的錯誤回應訊息。

成功

這個欄位是布林值，如果撤銷方法呼叫成功，則設為 true，失敗則設為 false。

錯誤

這個欄位是字串值，如果撤銷方法呼叫失敗，則會包含詳細的錯誤訊息；如果成功，則未定義。

Sign in with Google JavaScript API 參考資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

方法：google.accounts.id.initialize

資料類型：IdConfiguration

client_id

color_scheme

auto_select

callback

login_uri

native_callback

cancel_on_tap_outside

prompt_parent_id

Nonce

essential_claims

背景資訊

state_cookie_domain

ux_mode

allowed_parent_origin

intermediate_iframe_close_callback

itp_support

login_hint

HD 高畫質

use_fedcm_for_prompt

use_fedcm_for_button

button_auto_select

方法：google.accounts.id.prompt

資料類型：PromptMomentNotification

資料類型：CredentialResponse

憑證

select_by

州

方法：google.accounts.id.renderButton

資料類型：GsiButtonConfiguration

屬性類型

類型

主題

大小

文字

形狀

logo_alignment

寬度

語言代碼

click_listener

州

資料類型：憑證

方法：google.accounts.id.disableAutoSelect

方法：google.accounts.id.storeCredential

方法：google.accounts.id.cancel

程式庫載入回呼：onGoogleLibraryLoad

方法：google.accounts.id.revoke

資料類型：RevocationResponse

成功

錯誤

Sign in with Google JavaScript API 參考資料