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

使用 FedCM API 進行 Google 登入

本指南說明第三方 Cookie 淘汰對 Google 登入平台程式庫。主題包括時間軸和如要確保程式庫回溯相容更新，請參閱後續步驟：進行影響評估並驗證使用者登入程序，正常運作，並視需要更新網頁應用程式的操作說明。管理轉換期的選項，以及取得說明的方式課程單元

圖書館狀態

所有新的網頁應用程式都會遭到封鎖，無法使用已淘汰的 Google 登入平台但使用程式庫的應用程式仍可繼續進行，直到另行通知為止。A 罩杯資料庫的最終停用日期 (關閉) 尚未確定。詳情請參閱停止支援和停用。

Chrome 的 Privacy Sandbox 封鎖第三方 Cookie 會影響網頁應用程式並使用 Google 登入平台程式庫為保留現有行為不必使用第三方 Cookie，可透過回溯相容的更新應用程式會將 FedCM API 新增至這個程式庫。雖然大部分變更都能流暢執行，更新導入了使用者同意聲明提示和 iframe 之間的差異 permissions-policy和內容安全政策 (CSP)。這些變更都可能會影響網頁應用程式，且需要變更應用程式的程式碼和網站此外還會從 0 自動調整資源配置您完全不必調整資源調度設定

在轉換期間，您可以透過設定選項來控管是否要 FedCM API 會在使用者登入時使用。

時間軸

上次更新時間：2024 年 7 月

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

2023 年 3 月：Google 登入平台停止支援資源庫。
2024 年 1 月：Chrome 封鎖 1% 的第三方 Cookie，Google 登入第三方 Cookie 將暫時例外狀況視為平台程式庫封鎖淘汰試用計畫
2024 年 7 月的過渡期開始，Google 登入平台資料庫對 FedCM API 新增支援。根據預設，Google 會控制的登入要求數量。網頁應用程式可能會請使用 use_fedcm 參數明確覆寫此行為。
Google 強制採用 FedCM API (日期待定) 登入平台程式庫，之後會忽略 use_fedcm 參數。且所有使用者登入要求都會使用 FedCM。

改用 FedCM API 後，Google 登入平台資料庫將停止服務受到第三方 Cookie 封鎖影響第三方 Cookie 相關更新內容封鎖詳情，請查看 Chrome 的 Privacy Sandbox 時程。

後續步驟

您可選擇以下三種做法：

進行影響評估，並在必要時更新網頁應用程式。這個方法會評估需要變更網頁應用程式的功能，。如需操作說明，請參閱本指南的下一節。
移至 Google Identity 服務 (GIS) 程式庫。移至最新強烈建議使用支援登入資料庫。操作步驟如下：這些操作說明。
不採取任何行動。您的網頁應用程式會在 Google 登入程式庫將遷移至 FedCM API，讓使用者登入。這就是正常運作，但使用者無法登入即可快速導入 API

進行影響評估

請按照下列操作說明，判斷網頁應用程式是否可以順利更新或是進行回溯相容的更新，或是否需要變更完整的 Google 登入平台資料庫後，使用者無法登入也採用 FedCM API

設定

瀏覽器 API 和最新版本的 Google 登入平台程式庫有。

進行後續步驟前：

請更新至最新版的 Chrome。Android 版 Google Chrome 必須使用 M128 以上版本，因此無法使用舊版測試。
開啟 chrome://flags 並將下列特徵設為這些值：
- 如果網站使用內容安全政策，#fedcm-authz 已啟用封鎖 https://accounts.google.com/gsi/ottoken。
- 已啟用 #tracking-protection-3pcd
- #third-party-cookie-deprecation-trial 已停用
- 已停用 #tpcd-metadata-grants
- #tpcd-heuristics-grants 已停用
並重新啟動 Chrome
初始化 Google 登入平台時，將 use_fedcm 設為 true 您網頁應用程式的功能庫一般來說，初始化作業如下所示：
- gapi.client.init({use_fedcm: true})，或
- gapi.auth2.init({use_fedcm: true})，或
- gapi.auth2.authorize({use_fedcm: true})。
撤銷 Google 登入平台資料庫的快取版本。由於程式庫的最新版本，因此通常不需要執行這個步驟加入 api.js、client.js 或 <script src> 標記中使用 platform.js (該要求可能會使用上述任一個標記) 程式庫的軟體包名稱)。
確認 OAuth 用戶端 ID 的 OAuth 設定：
1. 開啟 Google API Console的「憑證」頁面
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 登入相關的錯誤或警告資源庫。
重複這個程序，直到沒有任何錯誤，而你可以順利登入。您可以藉由確認 BasicProfile.getEmail() 會傳回您的電子郵件地址， GoogleUser.isSignedIn() 是 True。

找出 Google 登入資料庫要求

檢查permissions-policy和內容安全政策是否已變更檢查 Google 登入平台資料庫的要求。方法是使用程式庫的名稱和來源找出要求：

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

例如以「網域」欄中的「apis.google.com」進行篩選， platform.js在「名稱」名稱欄中。

檢查 iframe 權限政策

您的網站可能會跨來源使用 Google 登入平台程式庫 iframe。如果是的話，請務必更新。

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

same-site或 same-origin，則不適用跨來源政策，且不適用需要修改
如果使用 iframe，可能需要變更 cross-origin。

如何確認 iframe 是否存在：

在 Chrome 開發人員工具中選取「Elements」面板，然後
按下 Ctrl + F 鍵，即可在文件中尋找 iframe。

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

將 allow="identity-credentials-get" 權限政策新增至上層 iframe。

針對文件中的每個 iframe 重複此程序。因為 iframe 可以是巢狀結構請務必在所有父項 iframe 中加入 allow 指令。

檢查內容安全政策

如果您的網站使用內容安全政策，您可能需要將 CSP 更新為允許使用 Google 登入資料庫

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

如果沒有找到標頭，則不需要修改。否則，請檢查是否有任何這些 CSP 指令會定義在 CSP 標頭中，並透過下列方式更新：

正在新增https://apis.google.com/js/、https://accounts.google.com/gsi/，和 https://acounts.google.com/o/fedcm/ 傳送至任何 connect-src。 default-src 或 frame-src 指令。
新增至 script-src 的 https://apis.google.com/js/bundle-name.js 指令。將 bundle-name.js 替換為 api.js、client.js 或 platform.js 是以程式庫組合文件要求為依據。

檢查使用者提示是否有變更

使用者提示行為存在一些差異，FedCM 新增了強制回應對話方塊並更新使用者啟用規定。

強制回應對話方塊

FedCM 互動對話方塊的圖片

檢查網站的版面配置，確認基礎內容可以安全覆蓋並暫時被瀏覽器的強制回應對話方塊遮住。如果這是因此，您可能需要調整某些元素的版面配置或位置。

啟用使用者

FedCM 載明新版使用者啟用規定。按下按鈕或點選連結是使用者手勢的例子，這類手勢允許第三方來源發出網路要求或儲存資料使用 FedCM 時使用者同意的情況：

使用者先透過新的瀏覽器執行個體登入網頁應用程式，或
系統會呼叫 GoogleAuth.signIn。

現在使用者登入您的網站後，初始化 Google 登入資料庫時使用者的登入資訊使用 gapi.auth2.init，無需進一步使用者互動。

由於第三方 Cookie 淘汰，除非使用者先完成 FedCM 登入流程至少一次。

選擇採用 FedCM 並呼叫 GoogleAuth.signIn，日後也同樣適用使用者造訪您的網站，gapi.auth2.init 就可以獲得使用者的登入系統進行初始化時，使用者不需與使用者互動。

常見用途

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

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

在這個demo中，<div> 元素和類別會轉譯按鈕，如果是已登入的使用者，頁面 onload 事件會傳回使用者憑證需要使用者互動才能登入及建立新的會很有幫助

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

使用者手勢，<div> 元素 onclick 事件，呼叫 auth2.signIn 或登出時auth2.signOut。
建立自訂 Google 登入按鈕

在示範一中，自訂屬性可用來控制如果已登入按鈕，且已登入的使用者，則會顯示在第 onload 頁事件則會傳回使用者憑證需要使用者互動建立新的工作階段。

程式庫初始化是透過 onload 事件完成 platform.js 程式庫和按鈕，由 gapi.signin2.render 顯示。

使用者手勢，按下登入按鈕並呼叫 auth2.signIn。

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

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

使用者手勢，<div> 元素 onclick 事件，呼叫 auth2.signIn (在登入時使用「auth2.attachClickHandler」功能)，或登入裝置上的 auth2.signOut 。
監控使用者的工作階段狀態

在這個demo中，按下按鈕的用途是讓使用者登入和登出。需要使用者互動，才能登入及建立新的工作階段。

程式庫初始化是直接呼叫 gapi.load 完成， gapi.auth2.init，之後gapi.auth2.attachClickHandler() 已使用 script src 載入 platform.js。

使用者手勢，<div> 元素 onclick 事件，呼叫 auth2.signIn (在登入時使用「auth2.attachClickHandler」功能)，或登入裝置上的 auth2.signOut 。
要求其他權限

在這個demo中，按下按鈕可用來要求額外的 OAuth 2.0 取得新的存取權杖；對於已登入的使用者，則第 onload 頁事件會傳回使用者憑證。需要使用者互動登入及建立新的工作階段

程式庫初始化是由onload 呼叫 gapi.signin2.render 來增加 platform.js 程式庫。

使用者手勢，按一下 <button> 元素，就會觸發針對使用 googleUser.grant 或 auth2.signOut 等其他 OAuth 2.0 範圍使用者登出時
使用事件監聽器整合 Google 登入

在這個demo中，已登入的使用者會看到第 onload 頁事件則會傳回使用者憑證需要使用者互動建立新的工作階段。

使用起始函式在載入文件時完成程式庫初始化並呼叫 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler。下一個是auth2.isSignedIn.listen和 auth2.currentUser.listen的用途是設定以下項目的變更通知：工作階段狀態最後，呼叫 auth2.SignIn 以傳回。

使用者手勢，<div> 元素 onclick 事件，呼叫 auth2.signIn (在登入時使用「auth2.attachClickHandler」功能)，或登入裝置上的 auth2.signOut 。
伺服器端應用程式適用的 Google 登入功能

在這個demo中，使用者手勢可用於要求 OAuth 2.0 驗證碼而 JS 回呼會進行 HC 呼叫，將回應傳送至後端伺服器進行驗證。

使用 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。

強制採用設定後，系統就會忽略所有 use_fedcm 設定， Google 登入平台程式庫。

取得說明

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