遷移至 FedCM

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

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

總覽

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

大多數網站會透過回溯相容的更新到 Google Identity 服務 JavaScript 程式庫，順暢地進行遷移作業。

提示： 在 Google 實驗和 Chrome 來源測試期間，登入您網站的使用者總數中，會有一定比例的使用者使用 FedCM API。實際比例可能因情況而異，如有變更，恕不另行通知。在 FedCM 必須對所有登入作業強制要求之前，請使用 data-use_fedcm_for_prompt 或 use_fedcm_for_prompt 選擇登入流程。這麼做可改善偵錯、收集指標，或是在完成遷移後將所有登入切換至 FedCM 的能力。

自動登入功能更新

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 時，One Tap 會顯示網域名稱，而非應用程式名稱。

使用 FedCM	未使用 FedCM

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

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

使用 FedCM	未使用 FedCM

多工作階段

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

使用 FedCM	未使用 FedCM

事前準備

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

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

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

• 如果 Chrome 瀏覽器為 119 以下版本，請開啟 chrome://flags 並啟用 FedCmWithoutThirdPartyCookies 實驗功能。在 Chrome 瀏覽器 120 以上版本中，您不需要執行這項步驟。

遷移網頁應用程式

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

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

• HTML，將 data-use_fedcm_for_prompt 屬性設為 true。

• JavaScript，將 IdConfiguration 物件中的 use_fedcm_for_prompt 設為 true。

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 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 代碼中。

  注意： 中介 Iframe API 支援 FedCM 跨來源 iframe。不需要額外屬性。不過，如果您使用 Intermediate Iframe API 在另一個 iframe 中嵌入網頁，則必須在所有父級 iframe 中新增 allow="identity-credentials-get" 屬性。啟用 FedCM，以便測試並確保所有層級都已正確設定權限政策。

  準備 One Tap 提示未顯示的相關問題。其他來源網站可能會在 iframe 中嵌入您的 One Tap 網頁。您可能會收到更多使用者或其他網站擁有者提供的 One Tap 相關支援單。雖然只有網站擁有者可以在自己的網頁上進行更新，但你可以採取下列措施來減輕影響：

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

• 視情況更新開發人員常見問題頁面。

• 請告知支援團隊這項即將實施的異動，並提前準備好對查詢做出回應。

• 主動與受影響的合作夥伴、客戶或網站擁有者聯絡，確保 FedCM 順利過渡。

  注意： 在受影響的網頁中，Chrome 瀏覽器開發人員工具主控台應會顯示錯誤訊息：[GSI_LOGGER]: FedCM get() rejects with NotAllowedError: The 'identity-credentials-get' feature is not enabled in this document.

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

這項步驟為選用步驟，因為並非所有網站都會選擇定義 CSP。

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

• 如果您的 CSP 適用於目前的 One Tap，且您未使用 connect-src、frame-src、script-src、style-src 或 default-src，則不需要進行任何變更。

• 否則，請按照這份指南設定 CSP。如果未正確設定 CSP，FedCM One Tap 就不會顯示在網站上。

  注意： 在受影響的網頁上，Chrome 瀏覽器開發人員工具主控台應會顯示錯誤訊息：[GSI_LOGGER]: FedCM get() rejects with NetworkError: Failed to execute 'get' on 'CredentialsContainer': Refused to connect to 'https://accounts.google.com/gsi/fedcm.json' because it violates the document's Content Security Policy.

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

針對 AMP 提供的使用者登入支援功能是 GIS 的選用功能，您的網站應用程式可能已實作這項功能。出現這種情況時

刪除以下項目的所有參照：

• 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 分析工具 (PSAT) 是 Chrome 開發人員工具的擴充功能，可協助採用 FedCM 等其他 API。這項工具會掃描網站，找出受影響的功能，並提供建議變更清單。