迁移到 FedCM

本指南可帮助您了解 Federated Credentials Management API (FedCM) 对您的 Web 应用所做的变更。

启用 FedCM 后，浏览器会显示用户提示，并且不使用第三方 Cookie。

概览

Privacy Sandbox for the Web 和 Chrome 从 Web 中移除第三方 Cookie 会给 Google Identity 服务和用户登录带来重大变化。

FedCM 可实现更私密的登录流程，而无需使用第三方 Cookie。浏览器会控制用户设置、显示用户提示，并且仅在用户明确同意后才会与 Google 等身份提供方联系。

对于大多数网站，可以通过对 Google Identity 服务 JavaScript 库的向后兼容更新无缝进行迁移。

提示 ：在 Google 实验和 Chrome 源试用期间，在登录您网站的用户总数中，一定比例的用户将使用 FedCM API。具体百分比可能会有所不同，如有更改，恕不另行通知。在 FedCM 成为所有登录方式的强制要求之前，请使用 data-use_fedcm_for_prompt 或 use_fedcm_for_prompt 选择登录流程，这样做可能会提高您在完成迁移后调试、收集指标或将所有登录方式切换到 FedCM 的能力。

有关自动登录功能的最新动态

适用于 Google Identity 服务的联合凭据管理 (FedCM) Beta 版已于 2023 年 8 月发布。许多开发者测试了该 API，并提供了宝贵的反馈。

Google 从开发者那里收到的一种回答是关于 FedCM 自动登录流程用户手势要求。为加强隐私保护，Chrome 要求用户在每个 Chrome 实例中重新确认他们想要使用 Google 帐号登录该网站，即使在 FedCM 发布之前批准了网站也是如此。这种一次性重新确认是通过点击一键式提示实现的，展示了用户登录的意图。这项变更可能会导致某些网站的自动登录转化率最初中断。

最近在 M121 中，Chrome 对 FedCM 自动登录流程用户体验进行了更改。只有在第三方 Cookie 受限时，才需要重新确认。这意味着：

1. 在第三方 Cookie 限制在 2024 年第 3 季度提高到 100% 之前，FedCM 自动登录不要求回访用户重新确认。如果用户使用 FedCM 界面重新确认，此重新确认将计入 3PCD 后时代的用户手势要求。

2. FedCM 自动登录将在用户当前手动限制第三方 Cookie 时或在将来的 Chrome 中默认限制第三方 Cookie 时检查重新确认状态。

根据这一变更，我们建议所有自动登录开发者尽快迁移到 FedCM，以减少对自动登录转化率的干扰。

对于自动登录流程，即使您的网站选择启用 FedCM，GIS JavaScript 也不会在旧版 Chrome（M121 之前）上触发 FedCM。

用户体验历程差异

使用 FedCM 和不采用 FedCM 的一键式体验是类似的，只有细微差异。

单次会话新用户

使用 FedCM 时，一键显示域名而不是应用名称。

使用 FedCM	不启用 FedCM

单次会话回访用户（已停用自动登录）

使用 FedCM 时，一键显示域名而不是应用名称。

使用 FedCM	不启用 FedCM

单次会话回访用户（已启用自动登录）

使用 FedCM 时，用户可以点击 X 在 5 秒内取消自动登录，而无需点击取消按钮。

使用 FedCM	不启用 FedCM

多次会话

使用 FedCM 时，一键显示域名而不是应用名称。

使用 FedCM	不启用 FedCM

准备工作

检查您的浏览器设置和版本是否支持 FedCM API，建议更新到最新版本。

• FedCM API 可在 Chrome 117 或更高版本中使用。

• Chrome 中的第三方登录设置处于启用状态。

• 如果您的 Chrome 浏览器是 119 或更低版本，请打开 chrome://flags 并启用实验性 FedCmWithoutThirdPartyCookies 功能。Chrome 浏览器 120 或更高版本不需要执行此步骤。

迁移 Web 应用

请按照以下步骤启用 FedCM、评估潜在的迁移影响，以及根据需要对现有 Web 应用进行更改：

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() 方法。

虽然系统仍会从 PromptMomentNotication 对象中的 google.accounts.id.prompt 回调调用跳过时刻 isSkippedMoment()，但不会提供详细原因。从代码中移除任何依赖于 getSkippedReason() 方法的代码。

请注意，启用 FedCM 后，已关闭的时刻通知 isDismissedMoment() 和相关的详细原因方法 getDismissedReason() 保持不变。

4. 从 data-prompt_parent_id 和 intermediate_iframes 中移除 position 样式属性。

浏览器会控制用户提示的大小和位置，不支持在桌面设备上一键快捷功能实现自定义位置。

5. 根据需要更新页面布局。

浏览器控制用户提示的大小和位置。根据各个页面的布局，某些内容可能会叠加为“一键快捷功能”在桌面设备上的自定义位置，而不受样式属性、data-prompt_parent_id、intermediate_iframes、自定义 iframe 和其他创意方式的支持。

更改页面布局，以在重要信息被遮盖时改善用户体验。即使您认为“一键快捷”提示位于默认位置，也不要围绕该提示构建用户体验。由于 FedCM API 是由浏览器中介的，因此不同的浏览器供应商对提示的位置可能会略有不同。

6. 如果您的 Web 应用从跨源 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，该 iframe 会嵌入一个页面 (https://logins.example.com)。

• 这个嵌入式页面 (https://logins.example.com) 还包含一个名为“iframe B”的 iframe，它可进一步嵌入托管一键快捷功能的页面 (https://onetap.example2.com)。

  为了确保“一键点击”功能可以正确显示，必须将该属性同时添加到 iframe A 和 iframe B 代码中。

  注意 ：中间 Iframe API 支持 FedCM 跨源 iframe。无需其他属性。不过，如果您在另一个 iframe 中使用中间 Iframe API 嵌入一个页面，则必须将 allow="identity-credentials-get" 属性添加到所有父 iframe。启用 FedCM，以测试并确保所有层均正确设置了权限政策。

  针对未显示一键式提示的问询准备。 其他来源不同的网站可能会将托管一键快捷功能的网页嵌入到其 iframe 中。您可能会收到更多来自最终用户或其他网站所有者的“一键快捷功能”相关问题的支持服务工单。虽然只有网站所有者在其网页上才能进行更新，但您可以采取以下措施来减轻影响：

• 更新您的开发者文档，添加如何正确设置 iframe 来调用您的网站。您可以在文档中提供指向此页面的链接。

• 更新开发者常见问题解答页面（如果适用）。

• 请告知您的支持团队这一即将发生的变化，并提前准备好回复咨询内容。

• 主动联系受影响的合作伙伴、客户或网站所有者，以便顺利完成 FedCM 转换。

7. 将这些指令添加到您的内容安全政策 (CSP) 中。

此步骤是可选的，因为并非所有网站都会选择定义 CSP。

• 如果您的网站未使用 CSP，则无需进行更改。

• 如果您的 CSP 适用于当前的一键快捷功能，而您没有使用 connect-src、frame-src、script-src、style-src 或 default-src，则无需进行任何更改。

• 否则，请按照此指南设置您的 CSP。如果没有正确的 CSP 设置，FedCM One Tap 将不会显示在网站上。

8. 取消 Accelerated Mobile Pages (AMP) 登录支持。

AMP 的用户登录支持是您的 Web 应用可能已实现的 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. 导航到应用中的一键式页面。

3. 确认显示了一键式提示，并且已安全地覆盖底层内容。

4. 在使用一键快捷功能登录应用时，确认将正确的凭据返回至您的端点或回调方法。

5. 如果已启用自动登录，请验证取消功能是否正常运行，并将正确的凭据返回给端点或回调方法。

一键式冷却期

点击右上角的“一键点按”图标 会关闭提示并进入冷却期，系统随即会暂时不显示“一键点按”提示。在 Chrome 中，如果您想在冷却期结束前再次显示一键快捷提示，可以重置冷却状态，方法是点击地址栏中的锁形图标，然后点击重置权限按钮。

自动登录静默期

使用 FedCM 测试自动登录一键登录功能时，每次尝试自动登录之间会有 10 分钟的静默期。静默期无法重置。您必须等待 10 分钟或使用其他 Google 帐号进行测试，才能再次触发自动登录。

实用资源

Privacy Sandbox Analysis Tool (PSAT) 是一款 Chrome 开发者工具扩展程序，具有专门的功能，可帮助开发者处理弃用第三方 Cookie 和采用替代 API 的问题。该工具会扫描您的网站中是否存在受影响的功能，并提供一系列建议的更改。