遷移至 FedCM

本指南可協助您瞭解 Federated Credentials Management API (FedCM) 提供的網頁應用程式變更。

啟用 FedCM 後，瀏覽器會顯示使用者提示，且不會使用第三方 Cookie。

總覽

網頁版 Privacy Sandbox 和 Chrome 從網路上移除第三方 Cookie 對 Google Identity 服務和使用者登入程序有重大異動。

FedCM 可提供更加私密的登入流程，而不必使用第三方 Cookie。瀏覽器會控制使用者設定、顯示使用者提示，且只有在明確徵得使用者同意後，才會與 Google 等識別資訊提供者聯絡。

針對大多數網站，Google Identity Services JavaScript 程式庫具有回溯相容性更新，可順利進行遷移。

自動登入功能最新消息

Google Identity 服務的 Federated Credential Management (FedCM) Beta 版已於 2023 年 8 月推出。許多開發人員測試過 API，並提供了寶貴的意見回饋。

Google 收到的一個回應是關於 FedCM 自動登入流程使用者手勢需求。為進一步保護隱私權，Chrome 會要求使用者重新確認，即使在 FedCM 推出前已核准網站，Chrome 仍會在每個 Chrome 執行個體中使用 Google 帳戶登入網站。只要按一下 One Tap 提示，就能確認使用者登入的意圖，這樣一次就能重新確認。這項變更可能會導致部分網站的自動登入轉換率一開始中斷。

最近在 M121 中，Chrome 已針對 FedCM 自動登入流程使用者體驗變更。只有在第三方 Cookie 受限的情況下，才需要重新確認。因此：

  1. 第三方 Cookie 限制在 2024 年第 3 季達到 100% 之前，回訪者不需要重新確認使用 FedCM 自動登入功能。如果使用者透過 FedCM UI 重新確認，這項重新確認動作將計入 3PCD 階段後的使用者手勢要求。

  2. 如果使用者目前手動限制第三方 Cookie，或日後 Chrome 中預設會限制第三方 Cookie，FedCM 自動登入就會檢查重新確認狀態。

透過這項變更，我們建議所有自動登入開發人員盡快遷移至 FedCM，以降低自動登入轉換率的干擾。

在 M121 以下版本的 Chrome 中，即使網站選擇加入 FedCM，GIS JavaScript 也不會在舊版 Chrome 中觸發 FedCM，因此使用自動登入流程時，GIS JavaScript 也不會觸發 FedCM。

使用者歷程差異

使用 FedCM 和沒有 FedCM 的 One Tap 體驗有小差異。

單一工作階段新使用者

One Tap 採用 FedCM 後，會顯示網域名稱，而不是應用程式名稱。

使用 FedCM 不使用 FedCM
使用 FedCM 的單一工作階段新使用者 不使用 FedCM 的情況下的單一工作階段新使用者

單工作階段回訪者 (停用自動登入功能)

One Tap 採用 FedCM 後，會顯示網域名稱，而不是應用程式名稱。

使用 FedCM 不使用 FedCM
使用 FedCM 的單一工作階段回訪使用者歷程 (停用自動登入功能) 沒有 FedCM 的單工作階段回訪使用者歷程 (停用自動登入功能)

單工作階段回訪者 (已啟用自動登入功能)

使用 FedCM 時，使用者可以按一下「X」X，在 5 秒內取消自動登入，不必點選「Cancel」按鈕。X

使用 FedCM 不使用 FedCM
使用 FedCM 的單一工作階段回訪使用者歷程 (已啟用自動登入功能) 沒有 FedCM 的單工作階段回訪使用者歷程 (已啟用自動登入功能)

多工作階段

One Tap 採用 FedCM 後，會顯示網域名稱，而不是應用程式名稱。

使用 FedCM 不使用 FedCM
使用 FedCM 的多工作階段使用者 沒有 FedCM 時的多工作階段使用者

事前準備

檢查瀏覽器設定和版本是否支援 FedCM API，建議更新至最新版本。

  • Chrome 117 以上版本支援 FedCM API。

  • Chrome 已啟用第三方登入設定。

  • 如果 Chrome 瀏覽器為 119 以下版本，請開啟 chrome://flags 並啟用 FedCmWithoutThirdPartyCookies 實驗性功能。Chrome 瀏覽器 120 以上版本無須執行這個步驟。

遷移網頁應用程式

請按照下列步驟啟用 FedCM、評估潛在的遷移影響，並視需要變更現有的網頁應用程式：

1. 使用以下方式初始化時，新增布林值標記以啟用 FedCM：

2. 在程式碼中移除使用 isDisplayMoment()、isDisplayed()、isNotDisplayed() 和 getNotDisplayedReason() 方法。

為了進一步保護使用者隱私，google.accounts.id.prompt 回呼不再傳回 PromptMomentNotication 物件中的任何顯示時刻通知。移除任何依附於顯示時間相關方法的程式碼。分別是 isDisplayMoment()、isDisplayed()、isNotDisplayed() 和 getNotDisplayedReason() 方法。

3. 在程式碼中移除 getSkippedReason() 方法。

雖然略過時刻 (isSkippedMoment()) 仍會透過 PromptMomentNotication 物件的 google.accounts.id.prompt 回呼呼叫，但不會提供詳細原因。從程式碼中移除所有依附於 getSkippedReason() 方法的程式碼。

請注意，啟用 FedCM 後，關閉時刻通知、isDismissedMoment() 和相關的詳細原因方法 getDismissedReason() 不會改變。

4. 從 data-prompt_parent_id 和 intermediate_iframes 移除 position 樣式屬性。

瀏覽器可控制使用者提示的大小和位置，系統不支援 One Tap 電腦版的自訂位置。

5. 視需要更新頁面的版面配置。

瀏覽器可控制使用者提示的大小和位置。視個別頁面的版面配置而定，部分內容可能會以任何方式重疊為 One Tap on Desktop 的自訂位置，如樣式屬性、data-prompt_parent_id、intermediate_iframes、自訂 iframe 和其他創意方式。

變更網頁版面配置，以便在有重要資訊遮蓋時改善使用者體驗。即使您認為 One Tap 提示位於預設位置，也請不要在其周圍建構使用者體驗。由於 FedCM API 是透過瀏覽器進行中介，因此不同瀏覽器供應商放置提示的位置可能會稍有不同。

6. 如果網頁應用程式從跨來源 iframe 呼叫 One Tap API，請將 allow="identity-credentials-get" 屬性加入上層頁框。

如果 iframe 的來源與父項來源不完全相同，系統會將 iframe 視為跨來源。例如：

  • 不同的網域：https://example1.com 和 https://example2.com
  • 不同的頂層網域：https://example.uk 和 https://example.jp

  • 子網域：https://example.com 和 https://login.example.com

    為了進一步保護使用者隱私，當從跨來源 iframe 呼叫 One Tap API 時，您必須在每個上層頁框 iframe 標記中加入 allow="identity-credentials-get" 屬性：

    <iframe src="https://your.cross-origin/onetap.page" allow="identity-credentials-get"></iframe>

    如果您的應用程式使用了含有另一個 iframe 的 iframe，您必須確保該屬性會新增至每個 iframe，包括所有子 iframe。

    我們舉以下情境為例：

  • 頂端文件 (https://www.example.uk) 包含名為「iframe A」的 iframe，後者嵌入了網頁 (https://logins.example.com)。

  • 這個嵌入的網頁 (https://logins.example.com) 也包含名為「iframe B」的 iframe，可進一步嵌入代管 One Tap 的網頁 (https://onetap.example2.com)。

    為了確保 One Tap 能夠正確顯示，您必須在 iframe A 和 iframe B 代碼內加入這個屬性。

    針對未顯示的 One Tap 提示問題做好準備。 來源不同的其他網站可能會將代管 One Tap 的網頁嵌入其 iframe 中。使用者或其他網站擁有者可能會收到更多與 One Tap 相關的支援單數量。雖然只有網站擁有者可以在自己的網頁上進行更新，不過您可以採取下列做法來降低影響：

  • 更新開發人員說明文件，說明如何正確設定 iframe，以呼叫網站。您可以在說明文件中提供這個頁面的連結。

  • 在適用情況下，請更新您的開發人員常見問題頁面。

  • 請告知支援團隊這項即將生效的異動，並提前做好準備，以便在提問前獲得回覆。

  • 主動聯絡受影響的合作夥伴、客戶或網站擁有者，以便順利進行 FedCM 轉換作業。

7. 將這些指令新增至內容安全政策 (CSP)。

由於並非所有網站都會選擇定義 CSP，因此您可以選擇執行這個步驟。

  • 如果網站上未使用 CSP，則無須進行任何變更。

  • 如果您的 CSP 適用於目前的 One Tap，且您並未使用 connect-src、frame-src、script-src、style-src 或 default-src，則無須變更。

  • 如果不是，請按照這份指南設定 CSP。如未正確設定 CSP，網站就無法顯示 FedCM One Tap 驗證機制。

8. 移除 Accelerated Mobile Pages (AMP) 登入支援。

AMP 的使用者登入支援是網頁應用程式已導入的選用功能，出現這種情況時

刪除以下內容的所有參照：

  • amp-onetap-google 自訂元素，以及

  • <script async custom-element="amp-onetap-google" src="https://cdn.ampproject.org/v0/amp-onetap-google-0.1.js"></script>

    請考慮將 AMP 的登入要求重新導向至網站的 HTML 登入流程。請注意，相關的 Intermediate Iframe Support API 不會受到影響。

測試及驗證遷移作業

根據上述步驟進行必要變更後，您可以驗證遷移作業是否成功。

  1. 確認瀏覽器支援 FedCM，且您已有 Google 帳戶工作階段。

  2. 前往應用程式中的 One Tap 頁面。

  3. 確認系統顯示 One Tap 提示，並以安全的方式重疊基礎內容。

  4. 透過 One Tap 登入應用程式時，確認將正確的憑證傳回您的端點或回呼方法。

  5. 如果已啟用自動登入功能，請確認取消作業可正常運作，且正確的憑證會傳回您的端點或回呼方法。

One Tap 等待期

按一下右上角的「One Tap」圖示 ，即可關閉提示並進入等待期，藉此暫時隱藏 One Tap 提示。在 Chrome 中，如果您希望在等待期結束前再次顯示 One Tap 提示，可以按一下網址列中的鎖頭圖示，然後點選「重設權限」按鈕，重設等待期狀態。

自動登入安靜期

使用 FedCM 測試自動登入 One Tap 時，每次嘗試自動登入之間有 10 分鐘的間隔時間。無法重設安靜期。您必須等待 10 分鐘或使用其他 Google 帳戶進行測試，才能再次觸發自動登入。

實用資源

Privacy Sandbox Analysis Tool (PSAT) 是 Chrome 開發人員工具擴充功能，具有專門的功能，可協助開發人員處理第三方 Cookie 的淘汰作業，並採用替代 API。這項功能會掃描您的網站找出受影響的功能，並提供建議變更的清單。