此页面由 Cloud Translation API 翻译。

使用 FedCM API 进行 Google 登录

本指南讨论了弃用第三方 Cookie 对 Google 登录平台库。主题包括时间轴和有关库向后兼容更新的后续步骤，以及如何执行影响评估并验证用户登录是否继续按预期运行，以及更新 Web 应用的说明（如果需要）。管理过渡期以及获取帮助的选项也包括在内

库的状态

所有新的 Web 应用都将无法使用已弃用的 Google 登录平台而使用该库的应用可以继续使用，直至另行通知。答该库的最终停用日期（停用）尚未确定。如需了解详情，请参阅弃用支持并停用。

Chrome 的 Privacy Sandbox 阻止第三方 Cookie 会影响 Web 应用使用 Google 登录平台库的应用。要保留现有行为而无需使用第三方 Cookie，将 FedCM API 添加到了此库中。虽然大多数更改都是无缝的，但更新引入了用户意见征求提示、iframe 方面的差异， permissions-policy 和内容安全政策 (CSP)。这些更改可能会影响您的 Web 应用，并需要对应用代码和网站进行更改配置。

在过渡期间，由一个配置选项控制用户登录期间会使用 FedCM API。

时间轴

上次更新时间：2024 年 7 月

下面列出了影响用户登录行为的日期和变化：

2023 年 3 月 停止支持 Google 登录平台库。
2024 年 1 月：Chrome 会阻止 1% 的第三方 Cookie（即 Google 登录）平台库暂时获得第三方 Cookie 豁免在弃用试用期间阻止运行。
2024 年 7 月过渡期开始，Google 登录平台库添加了对 FedCM API 的支持。默认情况下，Google 会控制在此期间使用 FedCM 发出了登录请求。Web 应用可以您可以使用 use_fedcm 参数明确替换此行为。
Google 强制采用（日期待定）FedCM API 登录平台库；之后 use_fedcm 参数将被忽略；并且所有用户登录请求均使用 FedCM。

迁移到 FedCM API 后，Google 登录平台库将不再用于受第三方 Cookie 屏蔽影响的广告。关于第三方 Cookie 的更新请参阅 Chrome 的 Privacy Sandbox 时间表。

后续步骤

您可以选择采用以下三种方法：

开展影响评估，并根据需要更新您的 Web 应用。此方法可评估需要更改 Web 应用的功能是否使用中。有关说明，请参阅本指南的下一部分。
移至 Google Identity 服务 (GIS) 库。迁移到强烈建议您使用受支持的登录库为此，请按照这些说明。
什么也不做。您的 Web 应用将在 Google 登录库改用 FedCM API 进行用户登录。这是最省时，但也存在用户无法登录您的 Web 应用。

开展影响评估

请按照以下说明确定您的 Web 应用是否可以无缝更新（例如通过向后兼容的更新），当 Google 登录平台库完全覆盖时，用户无法登录采用 FedCM API。

设置

浏览器 API 和最新版本的 Google 登录平台库。

在继续之前，请执行以下操作：

将桌面版 Chrome 更新到最新版本。Android 版 Chrome 需要 M128 或更高版本，无法使用早期版本进行测试。
打开 chrome://flags 并将以下功能设置为这些值：
- #fedcm-authz（如果您的网站使用内容安全政策）已启用阻止https://accounts.google.com/gsi/ottoken。
- #tracking-protection-3pcd 已启用
- #third-party-cookie-deprecation-trial 已停用
- #tpcd-metadata-grants 已停用
- #tpcd-heuristics-grants 已停用
然后重新启动 Chrome。
初始化 Google 登录平台时，将 use_fedcm 设置为 true 库。通常，初始化应如下所示：
- gapi.client.init({use_fedcm: true})，或者
- gapi.auth2.init({use_fedcm: true})，或者
- gapi.auth2.authorize({use_fedcm: true})。
使 Google 登录平台库的缓存版本失效。通常不需要执行此步骤，因为已安装了该库的最新版本（通过添加 api.js、client.js 或 <script src> 标记中的 platform.js（该请求可以使用以下任何一项：库的软件包名称）。
确认您的 OAuth 客户端 ID 的 OAuth 设置：
1. 打开 Google API Console的“凭据”页面
2. 验证您网站的 URI 是否包含在 已获授权的 JavaScript 来源。URI 包含架构和全限定主机名。例如 https://www.example.com。
  
  要点：对于本地测试或开发，请同时添加 http://localhost 和 http://localhost:<port_number>。
3. （可选）可以使用到端点的重定向返回凭据而不是通过 JavaScript 回调来托管。如果遇到这种情况验证您的重定向 URI 是否包含在已获授权的重定向 URI 中。重定向 URI 包括架构、完全限定主机名和路径并且必须遵循重定向 URI 验证规则。例如 https://www.example.com/auth-receiver。
  
  要点：使用 http 和 localhost 进行测试时，请设置 Referrer-Policy 标头 Referrer-Policy: no-referrer-when-downgrade。

测试

按照“设置”中的说明操作后：

关闭所有现有的 Chrome 无痕式窗口，然后打开新的无痕式窗口窗口。这样做会清除所有缓存的内容或 Cookie。
加载用户登录页面并尝试登录。
请按照本指南各部分中的说明确定并修复已知问题：
在控制台中查找与 Google 登录相关的任何错误或警告库。
重复此过程，直至不再出现任何错误，您就可以成功登录了。您可以通过确认以下操作来验证登录是否成功 BasicProfile.getEmail() 会返回您的电子邮件地址以及 GoogleUser.isSignedIn() 为 True。

找到 Google 登录库请求

检查 permissions-policy 和内容安全政策更改是否检查 Google 登录平台库的请求。为此，请使用库的名称和来源找到相应请求：

在 Chrome 中，打开开发者工具 Network 面板并重新加载页面。
使用 Domain 和 Name 列中的值找到库请求： <ph type="x-smartling-placeholder">
- 域名为 apis.google.com 且
- 名称是 api.js、client.js 或 platform.js。使用 Name 的值取决于文档请求的库包。

例如，在网域列中按 apis.google.com 进行过滤，并将 platform.js（在 Name 列中）。

检查 iframe 权限政策

您的网站可能在跨源应用中使用 Google 登录平台库 iframe。如果是这样，则需要进行更新。

完成查找 Google 登录库请求后说明，请在开发者工具中选择 Google 登录库请求网络面板，然后在以下位置找到 Sec-Fetch-Site 标头： Headers 标签页中的 Request Headers 部分。如果标头中的值：

same-site或 same-origin，则跨源政策不适用，并且更改。
如果使用了 iframe，则可能需要更改 cross-origin。

要确认是否存在 iframe，请执行以下操作：

在 Chrome 开发者工具中选择 Elements 面板，然后
使用 Ctrl-F 在文档中查找 iframe。

如果找到了 iframe，请检查文档以检查对 gapi.auth2 的调用情况函数或 script src 指令来加载 Google 登录库。如果遇到这种情况，请按以下指示操作：

将 allow="identity-credentials-get" 权限政策添加到父 iframe。

对文档中的每个 iframe 重复此过程。iframe 可以嵌套请务必将 allow 指令添加到所有周围的父 iframe 中。

查看内容安全政策

如果您的网站使用了内容安全政策，您可能需要将 CSP 更新为允许使用 Google 登录库。

完成查找 Google 登录库请求后说明，请在开发者工具中选择 Google 登录库请求网络面板，然后在以下位置找到 Content-Security-Policy 标头： Headers 标签页的 Response Headers 部分。

如果未找到该标头，则无需进行任何更改。否则，请查看这些 CSP 指令在 CSP 标头中定义，并通过以下方式更新：

正在添加https://apis.google.com/js/、https://accounts.google.com/gsi/、并将https://acounts.google.com/o/fedcm/分配给任何connect-src， default-src 或 frame-src 指令。
为 https://apis.google.com/js/bundle-name.js 添加到 script-src 指令。将 bundle-name.js 替换为 api.js、client.js 或 platform.js。

检查用户提示更改

用户提示行为存在一些差异，FedCM 添加了一个模态对话框并更新用户激活要求。

模态对话框

FedCM 模态对话框的图片

检查网站的布局，确认基础内容可以安全叠加，并被浏览器的模态对话框暂时遮挡。如果您可能需要调整某些元素的布局或位置。

用户激活

FedCM 包含更新后的用户激活要求。按某个按钮或例如，允许第三方来源点击链接的用户手势发出网络请求或存储数据使用 FedCM 时，浏览器会提示用户意见征求：

当用户首次使用新的浏览器实例登录 Web 应用时触发，或者
调用 GoogleAuth.signIn。

现在，如果用户以前登录过您的网站，您可以获取用户在初始化 Google Sign-In 库时的登录信息使用 gapi.auth2.init，而无需进行进一步的用户互动。

由于第三方 Cookie 已弃用，除非用户首次完成 FedCM 登录流程一次。

选择启用 FedCM 并在下次遇到相同的情况时致电 GoogleAuth.signIn，用户访问您的网站，gapi.auth2.init 可以获取用户的登录信息信息。

常见使用场景

Google 登录库的开发者文档包含指南和代码常见使用场景示例。本部分将讨论 FedCM 如何影响其行为

将 Google 登录功能集成到您的 Web 应用中

在此demo中，由一个 <div> 元素和一个类渲染该按钮，以及对于已登录的用户，页面 onload 事件会返回用户凭据。需要用户互动才能登录和创建新的会话。

库初始化由 g-signin2 类完成，该类会调用 gapi.load和gapi.auth2.init。

用户手势（<div> 元素 onclick 事件）调用 auth2.signIn 或者在退出时auth2.signOut。
构建自定义 Google 登录按钮

在演示 1 中，自定义属性用于控制登录按钮；对于已登录的用户，则为页面 onload 事件返回用户凭据。需要用户互动才能登录和建立新会话。

库初始化通过 onload 事件完成，对于 platform.js 库，并且按钮由 gapi.signin2.render 显示。

用户手势按登录按钮，会调用 auth2.signIn。

在演示 2 中，<div> 元素、CSS 样式和自定义图形用于控制登录按钮的外观。用户互动登录和建立新会话所需的资源。

库初始化在文档加载时使用 start 函数完成它会调用 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler。

用户手势（<div> 元素 onclick 事件）调用 auth2.signIn 在登录期间使用auth2.attachClickHandler或在登录状态下使用auth2.signOut 退出。
监控用户的会话状态

在此demo中，按下按钮来供用户登录和退出账号。需要用户互动才能登录和建立新会话。

库初始化是通过直接调用 gapi.load 完成的， gapi.auth2.init，之后 gapi.auth2.attachClickHandler() platform.js 是使用 script src 加载的。

用户手势（<div> 元素 onclick 事件）调用 auth2.signIn 在登录期间使用auth2.attachClickHandler或在登录状态下使用auth2.signOut 退出。
请求其他权限

在此demo中，按下按钮来请求额外的 OAuth 2.0 获取新的访问令牌，而对于已经登录的用户，页面 onload 事件会返回用户凭据。用户互动为必填项登录并建立新会话。

库初始化通过 onload 事件完成， platform.js 库（通过调用 gapi.signin2.render）。

用户手势点击 <button> 元素会触发对使用 googleUser.grant 或 auth2.signOut 的额外 OAuth 2.0 范围退出。
使用监听器集成 Google 登录

在此demo中，对于已登录的用户，页面 onload 事件返回用户凭据。需要用户互动才能登录和建立新会话。

库初始化在文档加载时使用 start 函数完成它会调用 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler。下一条：auth2.isSignedIn.listen auth2.currentUser.listen 用于设置对以下内容的更改通知：会话状态最后，调用 auth2.SignIn 以返回已登录的用户

用户手势（<div> 元素 onclick 事件）调用 auth2.signIn 在登录期间使用auth2.attachClickHandler或在登录状态下使用auth2.signOut 退出。
适用于服务器端应用的 Google 登录功能

在本demo中，用户手势用于请求 OAuth 2.0 身份验证代码以及 JS 回调进行 AJAX 调用以将响应发送到后端服务器进行验证。

使用 platform.js 的 onload 事件完成库初始化库，该库使用 start 函数来调用 gapi.load， gapi.auth2.init。

用户手势点击 <button> 元素会触发对通过调用 auth2.grantOfflineAccess 获得授权代码。
跨平台单点登录

FedCM 要求针对每个浏览器实例征得用户同意，即使 Android 用户也是如此请登录，则需获得一次性同意。

管理过渡期

在过渡期间，一定比例的用户登录可使用 FedCM、确切百分比可能会有所不同，并且可能会随时间而变化。默认情况下，Google 控件使用 FedCM 的登录请求数量，但您可以选择启用或停用使用 FedCM。过渡期结束时 FedCM 成为强制性要求，并且适用于所有登录请求。

如果选择选择加入，用户将先完成 FedCM 登录流程，同时选择提示用户完成现有的登录流程。这种行为使用 use_fedcm 参数控制。

选择启用

因此，您不妨控制一下是允许所有或部分登录您是否使用 FedCM API。为此，请在初始化时将 use_fedcm 设置为 true 平台库在这种情况下，用户登录请求使用 FedCM API。

选择停用

在过渡期间，有一定比例的用户尝试登录您的网站将使用 FedCM API。如果您需要更多时间来修改应用，您可以暂时选择停用 FedCM API。为此，请将初始化平台库时，将 use_fedcm 设置为 false。用户登录请求将不会使用 FedCM API。

强制采用后，系统会忽略所有 use_fedcm 设置， Google 登录平台库。

获取帮助

使用 google-signin 标签在 StackOverflow 中搜索或提问。