本頁面由 Cloud Translation API 翻譯而成。

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

本參考頁面說明 Sign-In JavaScript API。您可以使用這項 API，在網頁上顯示「一鍵登入」提示或「使用 Google 帳戶登入」按鈕。

方法：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
`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 權杖的隨機字串
`context`	One Tap 提示中的標題和字詞
`state_cookie_domain`	如要在父項網域及其子網域中呼叫「一鍵登入」，請將父項網域傳遞至這個欄位，以便使用單一共用 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 是否應使用 FedCM 按鈕 UX (桌機 M125 以上版本和 Android M128 以上版本)。預設值為 `false`。
`button_auto_select`	是否要為 FedCM 按鈕流程啟用自動選取選項。如果啟用這項功能，系統會自動登入具有有效 Google 工作階段的回訪使用者，略過帳戶選擇器提示。預設值為 `false`。

client_id

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

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

auto_select

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

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

callback

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

類型	必填	範例
函式	使用「一鍵登入」和 `popup` UX 模式時必須提供	`callback: handleResponse`

login_uri

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

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

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

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

詳情請參閱下表：

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

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

native_callback

這個欄位是 JavaScript 函式的名稱，負責處理瀏覽器內建憑證管理工具傳回的密碼憑證。詳情請參閱下表：

類型	必填	範例
函式	選用	`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"`

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

背景資訊

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

詳情請參閱下表：

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

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

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

state_cookie_domain

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

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

ux_mode

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

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

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

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

allowed_parent_origin

允許嵌入中繼 iframe 的來源。如果這個欄位存在，One Tap 會以中繼 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

當使用者在 One Tap UI 中輕觸「X」按鈕手動關閉 One Tap 時，系統會覆寫預設的中間 iframe 行為。預設行為是立即從 DOM 移除中繼 iframe。

intermediate_iframe_close_callback 欄位只會在中間 iframe 模式中生效。而且只會影響中繼 iframe，不會影響「一鍵登入」iframe。回呼叫用前，系統會移除「一鍵登入」使用者介面。

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

itp_support

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

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

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 按鈕 UX。預設值為 false。詳情請參閱下表：

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

button_auto_select

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

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

方法：google.accounts.id.prompt

呼叫 initialize() 方法後，google.accounts.id.prompt 方法會顯示「一鍵登入」提示或瀏覽器內建的憑證管理工具。請參閱下列方法程式碼範例：

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

一般來說，系統會在網頁載入時呼叫 prompt() 方法。由於 Google 端的會話狀態和使用者設定，系統可能不會顯示「輕觸一下」提示 UI。如要在不同時間點收到 UI 狀態通知，請傳遞函式來接收 UI 狀態通知。

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

顯示時機：呼叫 prompt() 方法後，通知包含布林值，指出是否顯示使用者介面。
略過時刻：如果系統自動取消或使用者手動取消「一鍵登入」提示，或是 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()`	這則通知是否與顯示時刻有關？注意：如果已啟用 FedCM，系統就不會觸發這項通知。詳情請參閱「遷移至 FedCM」頁面。
`isDisplayed()`	這則通知是否用於顯示時刻，且使用者介面是否已顯示？注意：如果已啟用 FedCM，系統就不會觸發這項通知。詳情請參閱「遷移至 FedCM」頁面。
`isNotDisplayed()`	這項通知是否與顯示時刻有關，但系統未顯示 UI？注意：如果已啟用 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()`	這則通知是否與跳過的時刻有關？
`getSkippedReason()`	系統略過該時刻的詳細原因。可能的值如下： `auto_cancel` `user_cancel` `tap_outside` `issuing_failed` 注意：如果已啟用 FedCM，系統就不支援這個方法。詳情請參閱「遷移至 FedCM」頁面。
`isDismissedMoment()`	這則通知是否與已關閉的時刻有關？
`getDismissedReason()`	詳細解雇原因。可能的值如下： `credential_returned` `cancel_called` `flow_restarted`
`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 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": "Elisa",
  "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_verfied也可能屬實，因為 Google 最初是在建立 Google 帳戶時驗證使用者，但第三方電子郵件帳戶的擁有權可能已變更。

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

select_by

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

使用者按下「One Tap」或「使用 Google 帳戶登入」按鈕，或使用免觸控的自動登入程序。
系統找到現有工作階段，或使用者選取並登入 Google 帳戶，以建立新工作階段。
與應用程式共用 ID 權杖憑證前，使用者必須
- 按下「確認」按鈕，同意共用憑證，或
- 先前已授予同意聲明，並使用「選取帳戶」選擇 Google 帳戶。

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

值	說明
`auto`	如果使用者已有工作階段，且先前已同意共用憑證，系統會自動登入。僅適用於不支援 FedCM 的瀏覽器。
`user`	使用者已開啟工作階段，且先前已授予同意聲明，並按下「以『繼續』」按鈕分享憑證。僅適用於不支援 FedCM 的瀏覽器。
`fedcm`	使用者按下「以『繼續』」按鈕，透過 FedCM 分享憑證。僅適用於支援 FedCM 的瀏覽器。
`fedcm_auto`	如果使用者已有工作階段，且先前已同意使用 FedCM One Tap 分享憑證，系統會自動登入該使用者。僅適用於支援 FedCM 的瀏覽器。
`user_1tap`	使用者按下「繼續以這個帳戶登入」單一輕觸按鈕，授予同意聲明並分享憑證。僅適用於 Chrome 75 以上版本。
`user_2tap`	使用者沒有現有工作階段，按下「以『繼續』」一鍵登入按鈕選取帳戶，然後按下彈出式視窗中的「確認」按鈕，授予同意聲明並分享憑證。適用於非 Chromium 架構的瀏覽器。
`itp`	使用者先前已授予同意聲明，且目前有現有工作階段，並在 ITP 瀏覽器中按下「一鍵登入」。
`itp_confirm`	使用者在 ITP 瀏覽器中按下「一鍵登入」，並按下「確認」按鈕授予同意聲明及分享憑證。
`itp_add_session`	使用者先前已授予同意聲明，但目前沒有現有工作階段，因此按下 ITP 瀏覽器上的「一鍵登入」按鈕，選取 Google 帳戶並分享憑證。
`itp_confirm_add_session`	使用者沒有現有工作階段，先在 ITP 瀏覽器上按下「一鍵登入」選取 Google 帳戶，然後按下「確認」按鈕同意並分享憑證。
`btn`	使用者已建立工作階段，且先前已同意授權，並按下「使用 Google 帳戶登入」按鈕，然後從「選擇帳戶」中選取要分享憑證的 Google 帳戶。
`btn_confirm`	使用者已開啟工作階段，並按下「使用 Google 帳戶登入」按鈕，然後按下「確認」按鈕，授予同意聲明並分享憑證。
`btn_add_session`	使用者先前已授予同意聲明，但目前沒有現有工作階段，因此按下「使用 Google 帳戶登入」按鈕，選取 Google 帳戶並分享憑證。
`btn_confirm_add_session`	使用者沒有現有工作階段，因此先按下「使用 Google 帳戶登入」按鈕選取 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`	標準按鈕主題。
`filled_blue`	藍色填滿按鈕主題。
`filled_black`	黑色填滿按鈕主題。

大小

按鈕大小。預設值為 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 屬性定義 JavaScript 函式，在使用者點選「使用 Google 帳戶登入」按鈕時呼叫該函式。

  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 帳戶登入」按鈕...) 訊息記錄到控制台中。

州

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

詳情請參閱下表：

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

資料類型：憑證

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

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

方法：google.accounts.id.disableAutoSelect

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

google.accounts.id.disableAutoSelect()

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

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

方法：google.accounts.id.storeCredential

這個方法是瀏覽器內建憑證管理工具 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。

錯誤

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

「使用 Google JavaScript API 登入」參考資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

方法：google.accounts.id.initialize

資料類型：IdConfiguration

client_id

auto_select

callback

login_uri

native_callback

cancel_on_tap_outside

prompt_parent_id

Nonce

背景資訊

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

成功

錯誤

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