使用 FedCM API 進行 Google 登入

警告：Google 登入程式庫可選擇使用 FedCM API，且日後使用 FedCM API 將成為必要條件。進行影響評估，確認使用者登入功能仍可正常運作。

Google 登入程式庫的支援已淘汰，詳情請參閱 淘汰和停用指南。

本指南將說明 Google 登入平台程式庫採用 FedCM API 的情況。主題包括程式庫的時間表和後續步驟、如何進行影響評估及驗證使用者登入功能是否能正常運作，以及在需要時更新網路應用程式的操作說明。此外，我們也會說明管理轉換期間的選項，以及如何取得協助。

程式庫狀態

任何新網頁應用程式都無法使用已淘汰的 Google 登入平台程式庫，但使用該程式庫的應用程式可以繼續使用，直到另行通知為止。尚未設定圖書館的最終停用日期 (關閉)。詳情請參閱「支援淘汰和停用」。

回溯相容性更新會將 FedCM API 新增至 Google 登入程式庫。雖然大部分的變更都會無縫接軌，但這次更新會對使用者提示、iframe permissions-policy 和內容安全政策 (CSP) 造成影響。這些變更可能會影響您的網頁應用程式，並需要變更應用程式程式碼和網站設定。

在轉換期間，設定選項會控制是否在使用者登入時使用 FedCM API。

過渡期結束後，所有使用 Google 登入程式庫的網路應用程式都必須使用 FedCM API。

時間軸

上次更新時間：2024 年 9 月

以下是影響使用者登入行為的日期和變更：

• 2023 年 3 月 淘汰 Google 登入平台資料庫的支援。
• 2024 年 7 月過渡期開始，Google 登入平台程式庫將新增 FedCM API 支援功能。根據預設，Google 會控制在這個期間使用 FedCM 的使用者登入要求百分比。網路應用程式可以使用 use_fedcm 參數明確覆寫這項行為。
• Google 登入平台程式庫2025 年 3 月強制採用 FedCM API，屆時系統會忽略 use_fedcm 參數，所有使用者登入要求都會使用 FedCM。

後續步驟

您可以選擇以下三種做法：

1. 進行影響評估，並視需要更新您的網頁應用程式。此方法會評估是否有需要變更網頁應用程式的功能正在使用中。本指南的下一節會提供操作說明。
2. 遷移至 Google Identity 服務 (GIS) 程式庫。強烈建議您改用最新且支援的登入程式庫。請按照這些操作說明操作。
3. 不採取任何行動。當 Google 登入程式庫遷移至 FedCM API 以便使用者登入時，您的網頁應用程式會自動更新。這是最省事的方法，但使用者可能無法登入您的網路應用程式。

進行影響評估

請按照下列操作說明，判斷您的網頁應用程式是否可透過回溯相容性更新無縫更新，或是需要進行變更，以免在 Google 登入平台程式庫完全採用 FedCM API 時，使用者無法登入。

設定

如要在使用者登入期間使用 FedCM，必須使用瀏覽器 API 和最新版的 Google 登入平台程式庫。

繼續之前：

• 更新至最新版的 Chrome 電腦版。Android 版 Chrome 需要 M128 以上版本，無法使用舊版進行測試。
• 在網頁應用程式中初始化 Google 登入平台程式庫時，請將 use_fedcm 設為 true。通常，初始化的樣子如下：
  • gapi.client.init({use_fedcm: true})，或
  • gapi.auth2.init({use_fedcm: true})，或
  • gapi.auth2.authorize({use_fedcm: true})。
• 讓 Google 登入平台程式庫的快取版本失效。通常不需要執行這個步驟，因為最新版本的程式庫會透過在 <script src> 標記中加入 api.js、client.js 或 platform.js，直接下載到瀏覽器 (要求可能會使用程式庫的任何套件名稱)。

• 確認 OAuth 用戶端 ID 的 OAuth 設定：

  1. 開啟 的「憑證」頁面

  2. 確認網站的 URI 已納入「已授權的 JavaScript 來源」。URI 僅包含配置和完整主機名稱。例如 https://www.example.com。

     重點提示： 如果是本機測試或開發作業，請同時新增 http://localhost 和 http://localhost:<port_number>。

  3. 您可以選擇透過重新導向至您代管的端點，而不是透過 JavaScript 回呼，來傳回憑證。如果是這種情況，請確認重新導向 URI 是否已納入「已授權的重新導向 URI」。重新導向 URI 包含配置、完整主機名稱和路徑，且必須符合重新導向 URI 驗證規則。例如：https://www.example.com/auth-receiver

     重點： 使用 http 和 localhost 進行測試時，請將網路應用程式中的 Referrer-Policy 標頭設為 Referrer-Policy: no-referrer-when-downgrade。

測試

按照「設定」中的操作說明操作後：

• 關閉所有現有的 Chrome 無痕式視窗，然後開啟新的無痕式視窗。這麼做會清除所有快取內容或 Cookie。
• 載入使用者登入頁面，並嘗試登入。

• 請按照本指南的這些章節中的操作說明，找出並修正已知問題：

  • 找出 Google 登入程式庫要求
  • 檢查 iframe 權限政策
  • 查看內容安全性政策
  • 檢查使用者提示變更

• 在主控台中查看是否有任何與 Google 登入程式庫相關的錯誤或警告。

• 重複這個程序，直到系統不再發生錯誤，您也能順利登入。您可以確認 BasicProfile.getEmail() 是否會傳回您的電子郵件地址，以及 GoogleUser.isSignedIn() 是否為 True，以驗證登入作業是否成功。

找出 Google 登入程式庫要求

檢查 Google 登入平台程式庫的要求，確認是否需要變更 permissions-policy 和 Content Security Policy。如要這麼做，請使用程式庫的名稱和來源找出要求：

• 在 Chrome 中，開啟開發人員工具的「網路」面板，然後重新載入網頁。
• 使用「Domain」和「Name」欄中的值，找出資料庫要求：
  • 網域為 apis.google.com，且
  • 名稱為 api.js、client.js 或 platform.js。Name 的具體值取決於文件要求的程式庫套件。

例如，將「網域」欄中的 apis.google.com 和「名稱」欄中的 platform.js 設為篩選條件。

檢查 iframe 權限政策

您的網站可能會在跨來源 iframe 中使用 Google 登入平台程式庫。如是，就需要更新。

按照「找出 Google 登入程式庫要求」的操作說明操作後，請在「開發人員工具」面板中選取 Google 登入程式庫要求，然後在「標頭」分頁的「要求標頭」部分找出 Sec-Fetch-Site 標頭。如果標頭的值為：

• same-site 或 same-origin，則跨來源政策不適用，因此不需要進行任何變更。
• 如果使用 iframe，可能需要變更 cross-origin。

如要確認是否有 iframe，請按照下列步驟操作：

• 在 Chrome 開發人員工具中選取「元素」面板，然後
• 使用 Ctrl + F 鍵找出文件中的 iframe。

如果找到 iframe，請檢查文件，確認是否有對 gapi.auth2 函式或 script src 指令的呼叫，這些指令會在 iframe 中載入 Google 登入程式庫。出現這種情況時：

• 將 allow="identity-credentials-get" 權限政策新增至父項 iframe。

對文件中的每個 iframe 重複執行這個程序。iframe 可嵌套，因此請務必在所有周圍的父項 iframe 中加入 allow 指示詞。

檢查內容安全政策

如果您的網站使用內容安全政策，您可能需要更新 CSP，以便使用 Google 登入程式庫。

按照「找出 Google 登入程式庫要求」的操作說明操作後，請在「開發人員工具」面板中選取 Google 登入程式庫要求，然後在「Headers」分頁的「Response Headers」部分找出 Content-Security-Policy 標頭。

如果找不到標頭，則不需要進行任何變更。否則，請檢查 CSP 標頭是否定義了任何 CSP 指令，並按照下列步驟更新：

• 將 https://apis.google.com/js/、https://accounts.google.com/gsi/ 和 https://acounts.google.com/o/fedcm/ 新增至任何 connect-src、default-src 或 frame-src 指令。

• 將 https://apis.google.com/js/bundle-name.js 新增至 script-src 指令。根據文件要求的程式庫套件，將 bundle-name.js 替換為 api.js、client.js 或 platform.js。

檢查使用者提示變更

使用者提示行為有些許差異，FedCM 會新增瀏覽器顯示的模式對話方塊，並更新使用者啟用要求。

重點： 同意聲明是針對每個瀏覽器例項，因此使用者即使先前已在其他裝置上同意，在其他裝置上使用 Chrome 時，仍須再次同意。

模式對話方塊

檢查網站版面配置，確認底層內容可安全重疊，並暫時遭到瀏覽器的模式對話方塊遮蔽。如果不是這樣，您可能需要調整網站某些元素的版面配置或位置。

注意： JavaScript 執行階段環境中無法使用模式對話方塊的大小和位置。

使用者啟用

FedCM 包含更新的使用者啟用規定。按下按鈕或點按連結，就是允許第三方來源發出網路要求或儲存資料的使用者手勢。使用 FedCM 時，瀏覽器會在下列情況下提示使用者同意：

• 使用者首次使用新瀏覽器例項登入網路應用程式，或
• 系統會呼叫 GoogleAuth.signIn。

目前，如果使用者曾登入您的網站，您就能在使用 gapi.auth2.init 初始化 Google 登入程式庫時取得使用者的登入資訊，而無須再進行其他使用者互動。除非使用者先前至少曾經歷 FedCM 登入流程一次，否則無法再執行這項操作。

只要選擇加入 FedCM 並呼叫 GoogleAuth.signIn，下次同一位使用者造訪您的網站時，gapi.auth2.init 就能在初始化期間取得使用者的登入資訊，無須使用者互動。

重點： 即使是在文件 onload 事件中，系統也必須在第一次呼叫 GoogleAuth.signIn 時，要求使用者手勢和同意提示。

常見用途

Google 登入程式庫的開發人員說明文件包含常見用途的指南和程式碼範例。本節將討論 FedCM 對這些行為的影響。

• 將 Google 登入整合至網頁應用程式

  在這個示範中，<div> 元素和類別會轉譯按鈕，而對於已登入的使用者，網頁 onload 事件會傳回使用者憑證。必須與使用者互動才能登入及建立新工作階段。

  程式庫初始化作業是由 g-signin2 類別完成，該類別會呼叫 gapi.load 和 gapi.auth2.init。

  使用者手勢 (<div> 元素 onclick 事件) 會在登入期間呼叫 auth2.signIn，或在登出時呼叫 auth2.signOut。

• 建立自訂 Google 登入按鈕

  在第一個示範中，我們使用自訂屬性控制登入按鈕的外觀，而對於已登入的使用者，頁面 onload 事件會傳回使用者憑證。您必須與使用者互動，才能登入並建立新的工作階段。

  程式庫初始化作業會透過 platform.js 程式庫的 onload 事件完成，而按鈕則會由 gapi.signin2.render 顯示。

  使用者手勢 (按下登入按鈕) 會呼叫 auth2.signIn。

  在第二個示範中，我們使用 <div> 元素、CSS 樣式和自訂圖形來控制登入按鈕的外觀。您必須與使用者互動，才能登入並建立新的工作階段。

  在載入文件時，程式庫會使用呼叫 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler 的 start 函式完成初始化。

  使用者手勢 (<div> 元素 onclick 事件) 會在登入時使用 auth2.attachClickHandler 呼叫 auth2.signIn，或在登出時呼叫 auth2.signOut。

• 監控使用者的工作階段狀態

  在這個示範中，按下按鈕可用於使用者登入和登出。使用者必須進行互動才能登入及建立新的工作階段。

  使用 script src 載入 platform.js 後，直接呼叫 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler()，即可完成程式庫初始化作業。

  使用者手勢 (<div> 元素 onclick 事件) 會在登入時使用 auth2.attachClickHandler 呼叫 auth2.signIn，或在登出時呼叫 auth2.signOut。

• 要求其他權限

  在這個示範中，按下按鈕可用於要求額外的 OAuth 2.0 範圍，取得新的存取權憑證，如果是已登入的使用者，頁面 onload 事件會傳回使用者憑證。您必須與使用者互動，才能登入並建立新的工作階段。

  資料庫初始化作業是由 platform.js 程式庫的 onload 事件透過呼叫 gapi.signin2.render 完成。

  使用者手勢 (點選 <button> 元素) 會在登出時，使用 googleUser.grant 或 auth2.signOut 觸發要求其他 OAuth 2.0 範圍。

• 使用事件監聽器整合 Google 登入

  在這個示範中，如果使用者已登入，網頁 onload 事件會傳回使用者憑證。使用者必須進行互動才能登入並建立新的工作階段。

  在載入文件時，程式庫會使用呼叫 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler 的 start 函式完成初始化。接著，我們會使用 auth2.isSignedIn.listen 和 auth2.currentUser.listen 設定會話狀態變更的通知。最後，系統會呼叫 auth2.SignIn，以便傳回已登入使用者的憑證。

  使用者手勢 (<div> 元素 onclick 事件) 會在登入時使用 auth2.attachClickHandler 呼叫 auth2.signIn，或在登出時呼叫 auth2.signOut。

• 伺服器端應用程式的 Google 登入

  在這個示範中，使用者手勢會用來要求 OAuth 2.0 驗證碼，而 JS 回呼會發出 AJAX 呼叫，將回應傳送至後端伺服器進行驗證。

  程式庫初始化作業會使用 platform.js 程式庫的 onload 事件，該事件會使用啟動函式呼叫 gapi.load 和 gapi.auth2.init。

  使用者手勢 (點按 <button> 元素) 會透過呼叫 auth2.grantOfflineAccess，觸發授權碼要求。

• 跨平台單一登入 (SSO)

  FedCM 需要每個瀏覽器例項的同意聲明，即使 Android 使用者已登入，也必須提供一次性同意聲明。

管理轉換期

在轉換期間，部分使用者登入作業可能會使用 FedCM，具體百分比可能會有所不同，且可能隨時間變動。根據預設，Google 會控制使用 FedCM 的登入要求數量，但您可以在轉換期間選擇是否要使用 FedCM。過渡期結束後，FedCM 就會成為強制要求，並用於所有登入要求。

選擇採用後，系統會引導使用者完成 FedCM 登入流程，選擇不採用後，系統會引導使用者完成現有的登入流程。這項行為可透過 use_fedcm 參數控制。

啟用

您可以控制網站的所有或部分登入嘗試是否使用 FedCM API。如要執行這項操作，請在初始化平台程式庫時，將 use_fedcm 設為 true。在這種情況下，使用者登入要求會使用 FedCM API。

選擇停用

在轉換期間，根據預設，使用者嘗試登入網站的次數中，會有部分會使用 FedCM API。如果需要更多時間變更應用程式，您可以暫時選擇不使用 FedCM API。如要執行這項操作，請在初始化平台程式庫時將 use_fedcm 設為 false。在這種情況下，使用者登入要求不會使用 FedCM API。

強制採用後，Google 登入平台程式庫會忽略任何 use_fedcm 設定。

取得說明

使用 google-signin 標記在 StackOverflow 上搜尋或提出問題。