迁移到 FedCM

本指南可帮助您了解 Federated Credential Management API (FedCM) 对 Web 应用带来的变化。

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

概览

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

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

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

适用于 Google Identity 服务的 Federated Credential Management (FedCM) Beta 版已于 2023 年 8 月发布。许多开发者都测试了该 API，并提供了宝贵的反馈。

Google 从开发者那里收到的回复之一与 FedCM 自动登录流程用户手势要求有关。为了更好地保护隐私，Chrome 要求用户在每次使用 Chrome 实例时重新确认是否要使用 Google 账号登录网站，即使用户在 FedCM 发布之前已批准该网站也是如此。用户只需点击一次“一键式登录”提示，即可完成这项一次性重新确认，以表明其有意登录。这项变更可能会导致某些网站的自动登录转化率在最初出现中断。

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

  1. 对于回访用户，FedCM 自动登录功能无需重新确认。如果用户通过 FedCM 界面重新确认，此重新确认将计入 3PCD 后时代的用户手势要求。

  2. 如果当前或日后的 Chrome 已默认手动限制第三方 Cookie，FedCM 自动登录功能将检查重新确认状态。

鉴于此项变更，我们建议所有自动登录开发者尽快迁移到 FedCM，以减少自动登录转化率的波动。

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

用户体验历程差异

使用 FedCM 和不使用 FedCM 的“一键式”体验相似，仅存在细微差异。

单次会话新用户

通过使用 FedCM，One Tap 会显示域名而不是应用名称。

使用 FedCM 不使用 FedCM
使用 FedCM 的单次会话新用户 不使用 FedCM 的单次会话新用户

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

通过使用 FedCM，One Tap 会显示域名而不是应用名称。

使用 FedCM 不使用 FedCM
使用 FedCM 的单次会话回访用户历程（自动登录已停用） 未启用 FedCM 的单次会话回访用户历程（自动登录功能处于停用状态）

单次会话回访用户（在启用自动登录的情况下）

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

使用 FedCM 不使用 FedCM
使用 FedCM 的单次会话回访用户历程（已启用自动登录） 未启用 FedCM 的单次会话回访用户历程（已启用自动登录）

多次会话

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

使用 FedCM 不使用 FedCM
使用 FedCM 的多次会话用户 未使用 FedCM 的多次会话用户

准备工作

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

  • FedCM API 适用于 Chrome 117 或更高版本。

  • Chrome 中启用了第三方登录设置。

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

迁移您的 Web 应用

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

1. 添加一个布尔标志，以便在初始化时使用以下命令启用 FedCM：

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. 如有必要，请更新页面布局。

浏览器会控制用户提示的大小和位置。根据各个网页的布局，部分内容可能会叠加显示，因为桌面版 One Tap 不支持任何方式的自定义位置，例如样式属性、data-prompt_parent_id、intermediate_iframes、自定义 iframe 和其他富有创意的方式。

更改网页布局，以便在重要信息被遮挡时改善用户体验。请勿围绕一键式提示构建用户体验，即使您认为它位于默认位置也是如此。由于 FedCM API 是通过浏览器中介的，因此不同浏览器供应商可能会略微不同地放置提示的位置。

6. 如果您的 Web 应用从跨源 iframe 调用 One Tap API，请向父级框架添加 allow="identity-credentials-get" 属性。

如果 iframe 的 origin 与父级 origin 不完全相同，则 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，该 iframe 进一步嵌入了托管 One Tap 的页面 (https://onetap.example2.com)。

    为确保“一键式付款”功能能够正常显示，必须同时向 Iframe A 和 Iframe B 代码添加此属性。

    准备好回答有关“一键式”提示未显示的问题。 其他具有不同来源的网站可能会在其 iframe 中嵌入托管 One Tap 的网页。您可能会收到更多与“一键式付款”不显示相关的支持服务工单，这些工单来自最终用户或其他网站所有者。虽然只有网站所有者可以在其网页上进行更新，但您可以执行以下操作来减少影响：

  • 更新您的开发者文档，在其中添加如何正确设置 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 的用户登录支持是 GIS 的一项可选功能，您的 Web 应用可能已实现该功能。如果遇到这种情况，

删除对以下内容的所有引用：

  • 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 开发者工具扩展程序，可帮助您采用 FedCM 等替代 API。该工具会扫描您的网站，找出受影响的功能，并提供建议的更改列表。