遷移至 FedCM

本指南可協助您瞭解 Federated Credentials Management API (FedCM) 對網頁應用程式所造成的變化。

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

總覽

FedCM 可讓使用者以更隱密的方式登入，不必使用第三方 Cookie。瀏覽器會控制使用者設定、顯示使用者提示，並在使用者明確同意後，才會聯絡 Google 等身分識別提供者。

對於大多數網站，Google Identity 服務 JavaScript 程式庫的回溯相容性更新可讓遷移作業順利進行。

自動登入功能更新

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

Google 收到開發人員的回應，指出 FedCM 自動登入流程的使用者手勢要求。為提升隱私權，Chrome 會要求使用者在每個 Chrome 執行個體中，重新確認是否要使用 Google 帳戶登入網站，即使使用者在 FedCM 推出前已核准該網站也一樣。只要單按一次 One Tap 提示，即可完成這項一次性的重新確認程序，以示使用者有意登入。這項異動可能會導致部分網站的自動登入轉換率初期出現中斷情形。

近期在 M121 中，Chrome 對 FedCM 自動登入流程的使用者體驗進行了變更。只有在第三方 Cookie 受到限制時，才需要重新確認。因此：

  1. FedCM 自動登入功能不需要針對回訪使用者進行重新確認。如果使用者透過 FedCM UI 重新確認，這次重新確認將計入 3PCD 後時代的使用者手勢要求。

  2. 當使用者今天手動限制第三方 Cookie，或在未來的 Chrome 中預設限制第三方 Cookie 時，FedCM 自動登入功能會檢查重新確認狀態。

因應這項異動，我們建議所有自動登入功能開發人員盡快改用 FedCM，以減少自動登入轉換率的影響。

對於自動登入流程，即使網站選擇啟用 FedCM，GIS JavaScript 也不會在舊版 Chrome (M121 之前) 上觸發 FedCM。

使用者歷程的差異

使用 FedCM 和不使用 FedCM 的 One Tap 體驗相似，僅有細微差異。

單一工作階段的新使用者

使用 FedCM 時，One Tap 會顯示頂層網域名稱，而非應用程式名稱。

使用 FedCM 未使用 FedCM
使用 FedCM 的單一工作階段新使用者 單一工作階段的新使用者 (未使用 FedCM)

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

使用 FedCM 時，One Tap 會顯示頂層網域名稱，而非應用程式名稱。

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

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

使用 FedCM 時，使用者可以按一下 X 取消自動登入，而非按一下「取消」按鈕。

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

多個工作階段

使用 FedCM 時，One Tap 會顯示頂層網域名稱，而非應用程式名稱。

使用 FedCM 未使用 FedCM
使用 FedCM 的多工作階段使用者 未使用 FedCM 的多個工作階段使用者

事前準備

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

  • FedCM API 適用於 Chrome 117 以上版本。

  • 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 不支援任何自訂位置，例如樣式屬性、data-prompt_parent_id、intermediate_iframes、自訂 iframe 和其他創意方式。

變更網頁版面配置，以改善重要資訊遭到遮蔽時的使用者體驗。即使您假設 One Tap 提示會顯示在預設位置，也不要以此為依據來建立使用者體驗。由於 FedCM API 是透過瀏覽器中介，不同瀏覽器供應商可能會將提示的位置稍微調整。

6. 如果您的網頁應用程式從跨來源 iframe 呼叫 One Tap API，請新增 allow="identity-credentials-get" 屬性至父項框架。

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

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

在跨來源 iframe 中使用 One Tap 時，使用者可能會遇到混淆的體驗。為了防止盜用憑證，One Tap 提示會顯示頂層網域名稱，而非 iframe 名稱。不過，ID 權杖會發送至 iframe 的來源。詳情請參閱這項 GitHub 問題。

由於這項差異可能會造成誤解，因此支援的方法是只在跨來源但同網站的 iframe 中使用 One Tap。舉例來說，頂層網域 https://www.example.com 上的網頁使用 iframe 嵌入 https://login.example.com 上的 One Tap 網頁。One Tap 提示會顯示「使用 google.com 登入 example.com」。

其他所有情況 (例如不同網域) 均不支援。請改用其他整合方法，例如：

  • 導入「使用 Google 帳戶登入」按鈕。
  • 在頂層網域上實作 One Tap
  • 使用 Google OAuth 2.0 端點，進一步自訂整合作業。
  • 如果您要在 iframe 中嵌入第三方網站，但無法修改其 One Tap 導入方式，可以防止 One Tap 提示訊息顯示在 iframe 中。如要這麼做，請從父項框架中的 iframe 標記移除 allow="identity-credentials-get" 屬性。這麼做可抑制提示，您就能直接引導使用者前往嵌入網站的登入頁面。

從跨來源 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，該 iframe 嵌入頁面 (https://logins.example.com)。

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

    為確保 One Tap 能正確顯示，您必須在 Iframe A 和 Iframe B 標記中同時加入這項屬性。

    準備 One Tap 提示未顯示的相關問題。其他來源網站可能會在 iframe 中嵌入您代管 One Tap 的網頁。您可能會收到更多與 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) 支援功能。

網站應用程式可能已實作 GIS 的選用功能，可支援 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 開發人員工具的擴充功能，可協助採用 FedCM 等其他 API。這項工具會掃描網站，找出受影響的功能，並提供建議變更清單。