本指南介绍了 Google 登录平台库对 FedCM API 的采用。主题包括:时间轴和后续步骤(用于对库进行向后兼容的更新)、如何进行影响评估并验证用户登录是否继续按预期运行,以及更新 Web 应用的说明(如有需要)。此外,还介绍了管理过渡期的选项以及如何获取帮助。
库的状态
任何新的 Web 应用都无法使用已弃用的 Google 登录平台库,而使用该库的应用可以继续使用,直至另行通知。该库的最终停用日期(关停)尚未确定。 如需了解详情,请参阅弃用支持和停用。
向后兼容的更新会将 FedCM API 添加到 Google 登录库中。 虽然大多数更改都是无缝的,但此次更新在用户提示、iframe 权限政策和内容安全政策 (CSP) 方面引入了一些差异。这些变更可能会影响您的 Web 应用,并需要您更改应用代码和网站配置。
在过渡期内,配置选项会控制在用户登录期间是否使用 FedCM API。
过渡期结束后,所有使用 Google 登录库的 Web 应用都必须使用 FedCM API。
时间表
上次更新时间:2025 年 4 月
以下是会影响用户登录行为的日期和变更:
- 2023 年 3 月 弃用对 Google 登录平台库的支持。
- 2024 年 7 月过渡期开始,Google 登录平台库添加了对 FedCM API 的支持。默认情况下,Google 会控制在此期间使用 FedCM 的用户登录请求的百分比,而 Web 应用可以使用
use_fedcm参数明确替换此行为。 - 2025 年 8 月:强制要求 Google 登录平台库采用 FedCM API。
后续步骤
您可以选择以下三种方式:
- 进行影响评估,并根据需要更新您的 Web 应用。此方法会评估是否使用了需要对 Web 应用进行更改的功能。本指南的下一部分提供了相关说明。
- 改用 Google Identity 服务 (GIS) 库。强烈建议您改用受支持的最新登录库。为此,请按照这些说明操作。
- 什么也不做。当 Google 登录库改用 FedCM API 进行用户登录时,您的 Web 应用会自动更新。这种方法的工作量最少,但存在用户无法登录 Web 应用的风险。
开展影响评估
请按照以下说明确定您的 Web 应用是否可以通过向后兼容的更新进行无缝更新,或者是否需要进行更改,以避免在 Google 登录平台库完全采用 FedCM API 时用户无法登录。
设置
在用户登录期间,必须使用浏览器 API 和最新版本的 Google 登录平台库才能使用 FedCM。
在继续之前:
- 更新到最新版本 Chrome 桌面版。Android 版 Chrome 需要 M128 或更高版本,无法使用更低版本进行测试。
在 Web 应用中初始化 Google 登录平台库时,将
use_fedcm设置为true。通常,JavaScript 初始化如下所示:gapi.client.init({use_fedcm: true}),或者gapi.auth2.init({use_fedcm: true}),或者gapi.auth2.authorize({use_fedcm: true})。
或者,您也可以使用
meta标记在 HTML 中启用 FedCM:<meta name="google-signin-use_fedcm" content="true">
使 Google 登录平台库的缓存版本失效。 通常,此步骤是不必要的,因为通过在
<script src>标记中添加api.js、client.js或platform.js,最新版本的库会直接下载到浏览器(请求可以使用库的任何这些软件包名称)。确认 OAuth 客户端 ID 的 OAuth 设置:
- 打开 Google API 控制台的“凭据”页面
验证您的网站 URI 是否包含在已获授权的 JavaScript 来源中。URI 仅包含架构和完全限定的主机名。例如
https://www.example.com。(可选)您也可以通过重定向到您托管的端点(而不是通过 JavaScript 回调)来返回凭据。如果是这种情况,请验证您的重定向 URI 是否包含在已获授权的重定向 URI 中。重定向 URI 包含 scheme、完全限定的主机名和路径,并且必须符合重定向 URI 验证规则。例如
https://www.example.com/auth-receiver。
测试
按照“设置”中的说明操作后:
- 关闭所有现有的 Chrome 无痕式窗口,然后打开一个新的无痕式窗口。这样做会清除所有缓存的内容或 Cookie。
- 加载用户登录页面并尝试登录。
请按照本指南中这些部分中的说明来识别和解决已知问题:
在控制台中查找与 Google 登录库相关的任何错误或警告。
重复此过程,直到不再出现错误并且您可以成功登录。 您可以通过确认
BasicProfile.getEmail()返回您的邮箱以及GoogleUser.isSignedIn()为True来验证是否成功登录。
找到 Google 登录库请求
通过检查对 Google 登录平台库的请求,检查是否需要更改 permissions-policy 和内容安全政策。为此,请使用库的名称和来源找到相应请求:
- 在 Chrome 中,打开开发者工具的网络面板,然后重新加载页面。
- 使用网域和名称列中的值找到库请求:
- 网域为
apis.google.com,且 - 名称为
api.js、client.js或platform.js。Name 的具体值取决于文档请求的库软件包。
- 网域为
例如,在网域列中过滤 apis.google.com,在名称列中过滤 platform.js。
检查 iframe 权限政策
您的网站可能会在跨域 iframe 中使用 Google 登录平台库。如果是,则需要更新。
按照找到 Google 登录库请求说明操作后,在开发者工具网络面板中选择 Google 登录库请求,然后在标头标签页的请求标头部分中找到 Sec-Fetch-Site 标头。如果标头的值为:
same-site或same-origin,则跨域政策不适用,无需进行任何更改。- 如果使用的是 iframe,则可能需要更改
cross-site。
如需确认是否存在 iframe,请执行以下操作:
- 在 Chrome 开发者工具中选择元素面板,
- 使用 Ctrl-F 在文档中查找 iframe。
如果找到 iframe,请检查文档,看看是否有对 gapi.auth2 函数或 script src 指令的调用,这些调用会在 iframe 中加载 Google 登录库。如果遇到这种情况,请按以下指示操作:
- 将
allow="identity-credentials-get"权限政策添加到父级 iframe。
对文档中的每个 iframe 重复此过程。iframe 可以嵌套,因此请务必将 allow 指令添加到所有周围的父级 iframe。
检查内容安全政策
如果您的网站使用内容安全政策,您可能需要更新 CSP 以允许使用 Google 登录库。
按照找到 Google 登录库请求说明操作后,在开发者工具网络面板中选择 Google 登录库请求,然后在标头标签页的响应标头部分中找到 Content-Security-Policy 标头。
如果未找到该标头,则无需进行任何更改。否则,请检查 CSP 标头中是否定义了以下任何 CSP 指令,并按如下方式进行更新:
向任何
connect-src、default-src或frame-src指令添加https://apis.google.com/js/、https://accounts.google.com/gsi/和https://acounts.google.com/o/fedcm/。将
https://apis.google.com/js/bundle-name.js添加到script-src指令。根据文档请求的库软件包,将bundle-name.js替换为api.js、client.js或platform.js。
检查用户提示是否发生变化
用户提示行为有一些变化,FedCM 添加了由浏览器显示的模态对话框,并更新了用户激活要求。
模态对话框
检查网站的布局,确认底层内容可以安全地被浏览器的模态对话框覆盖并暂时遮挡。如果不是这种情况,您可能需要调整网站某些元素的布局或位置。
用户激活
FedCM 包含更新后的用户激活要求。按下按钮或点击链接就是用户手势的示例,这些手势允许第三方源发出网络请求或存储数据。借助 FedCM,浏览器会在以下情况下提示用户同意:
- 用户首次使用新的浏览器实例登录 Web 应用,或
- 调用
GoogleAuth.signIn。
目前,如果用户之前登录过您的网站,您可以在使用 gapi.auth2.init 初始化 Google 登录库时获取用户的登录信息,而无需用户执行进一步的操作。除非用户已至少完成一次 FedCM 登录流程,否则无法再执行此操作。
通过选择启用 FedCM 并调用 GoogleAuth.signIn,当同一用户下次访问您的网站时,gapi.auth2.init 可以在初始化期间获取用户的登录信息,而无需用户互动。
常见应用场景
Google 登录库的开发者文档包含常见用例的指南和代码示例。本部分将讨论 FedCM 如何影响其行为。
-
在此演示中,
<div>元素和类会呈现按钮,对于已登录的用户,页面onload事件会返回用户凭据。需要用户互动才能登录并建立新会话。库初始化由
g-signin2类完成,该类会调用gapi.load和gapi.auth2.init。用户手势(
<div>元素onclick事件)会在登录期间调用auth2.signIn,或在退出登录时调用auth2.signOut。 -
在演示一中,自定义属性用于控制登录按钮的外观,对于已登录的用户,页面
onload事件会返回用户凭证。用户需要进行互动才能登录并建立新会话。库初始化是通过
platform.js库的onload事件完成的,按钮由gapi.signin2.render显示。用户手势(按下登录按钮)会调用
auth2.signIn。在演示 2 中,
<div>元素、CSS 样式和自定义图形用于控制登录按钮的外观。用户需要进行互动才能登录并建立新会话。库初始化是在文档加载时使用启动函数完成的,该函数会调用
gapi.load、gapi.auth2.init和gapi.auth2.attachClickHandler。用户手势(
<div>元素onclick事件)在登录期间使用auth2.attachClickHandler调用auth2.signIn,或在退出时调用auth2.signOut。 -
在此演示中,用户通过按按钮来登录和退出。 用户需要进行互动才能登录并建立新会话。
库初始化是通过在使用
script src加载platform.js后直接调用gapi.load、gapi.auth2.init和gapi.auth2.attachClickHandler()来完成的。用户手势(
<div>元素onclick事件)在登录期间使用auth2.attachClickHandler调用auth2.signIn,或在退出时调用auth2.signOut。 -
在此演示中,按下按钮可用于请求其他 OAuth 2.0 范围、获取新的访问令牌,对于已登录的用户,页面
onload事件会返回用户凭据。需要用户互动才能登录并建立新会话。库初始化由
platform.js库的onload事件通过调用gapi.signin2.render完成。用户手势(点击
<button>元素)会触发使用googleUser.grant或auth2.signOut请求其他 OAuth 2.0 权限范围的操作。 -
在此演示中,对于已登录的用户,页面
onload事件会返回用户凭据。用户需要进行互动才能登录并建立新会话。库初始化是在文档加载时使用启动函数完成的,该函数会调用
gapi.load、gapi.auth2.init和gapi.auth2.attachClickHandler。接下来,auth2.isSignedIn.listen和auth2.currentUser.listen用于设置会话状态更改通知。最后,系统会调用auth2.SignIn来返回已登录用户的凭据。用户手势(
<div>元素onclick事件)在登录期间使用auth2.attachClickHandler调用auth2.signIn,或在退出时调用auth2.signOut。 -
在此演示中,用户手势用于请求 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。
强制采用后,Google 登录平台库会忽略所有 use_fedcm 设置。
获取帮助
使用 google-signin 标签在 StackOverflow 上搜索或提问。