Google Identity Services 即将迁移到 FedCM API。请按照迁移指南查看可能发生的更改，并避免对网站的登录产生负面影响。

此页面由 Cloud Translation API 翻译。

集成注意事项

本分步指南可帮助您就所有重大集成问题做出决策。

摘要中的“使用 Google 账号登录”

以下是用户在您的网站上登录 / 注册的一般步骤。

用户登录 Google 网站。

如需使用“使用 Google 账号登录”功能，浏览器中应有一个有效的 Google 会话。只有在用户在加载您的网页之前已登录 Google 的情况下，系统才会触发一键式登录和自动登录功能。对于“使用 Google 账号登录”按钮流程，此步骤是可选的，因为用户在按下该按钮时会收到登录 Google 的提示。

要点：出于安全考虑，不允许在 iframe 中添加新的 Google 会话。
用户浏览您嵌入了“一键登录”“自动登录”或“使用 Google 账号登录”按钮的网页。

要点：您可以使用代码生成器生成代码，将“一键登录”“自动登录”和“使用 Google 账号登录”按钮嵌入到您的网页中。
用户与“一键式登录”“使用 Google 账号登录”按钮和后续的用户体验流程进行互动，以便：
- 选择一个有效的 Google 会话以继续。
- 征得最终用户同意与您的网站分享个人资料信息（如果尚未征得同意）。
要点：如果之前只有一个 Google 活跃会话已授予相应权限，并且您的网站已启用该功能，则会发生自动登录。
注意：自动登录只能在“一键登录”用户体验中发生，而不能在“使用 Google 账号登录”按钮用户体验中发生。

当浏览器中只有一个有效的 Google 会话时，
- 一键登录会自动选择唯一的会话，从而跳过账号选择器页面。
- “使用 Google 账号登录”按钮会保留在账号选择器页面上，以便用户在需要时添加新的 Google 会话。
如果所选的 Google 账号之前未用于您的网站，或者相应权限已被撤消，系统会显示一个意见征求页面。

获得批准后，Google 会记录相应决定，以便下次跳过意见征求页面。
使用 JavaScript 回调处理脚本或向后端服务提交帖子，共享包含用户姓名、电子邮件地址和个人资料照片的 JSON Web 令牌（也称为 ID 令牌）凭据。

将 ID 令牌返回到客户端上的 JavaScript 回调处理程序的目的不是让您在 JavaScript 代码中对其进行解码，而是让您以自己的方式将其提交到服务器。一个很好的示例是使用 XmlHttpRequest 来避免因提交帖子而导致网页重新加载。

要点：如需在不重新加载网页的情况下进行身份验证，常见做法是通过 JavaScript 回调处理程序接收 JWT 凭据，然后通过 XmlHttpRequest 将其提交到服务器。
在服务器端，系统会验证 Google 签发的 JWT 凭据，并将其用于在您的网站上创建新账号或建立经过身份验证的会话。

您将在自己的网站上管理用户登录状态。

用户的 Google 账号登录状态与您的应用是相互独立的，但在登录过程中，您知道用户已成功完成身份验证并登录其 Google 账号时，这两者之间存在关联。用户可以保持登录状态，也可以退出登录或切换到其他 Google 账号，同时在您的网站上保持已登录的有效会话。

总而言之，与基于密码的登录方式一样，“使用 Google 账号登录”提供了在 Web 上对用户进行身份验证的另一种方式。“使用 Google 账号登录”功能在身份验证后不会在您的网站上提供任何会话管理功能。

访问 Google API 和服务

虽然您已集成身份验证 API（如前所述），但如果您的网站需要代表已验证身份的用户访问 Google API 和服务，您可能还需要集成授权 API。身份验证会为您的网站提供 ID 令牌来验证用户身份，而授权会为您的网站提供（单独的）访问令牌和使用 Google API 和服务的权限。如需了解详情，请参阅为网站授权。

身份验证和授权的用户体验分离

如果您的网站需要同时调用身份验证 API 和授权 API，则必须在不同时间分别调用它们。请参阅将身份验证和授权时刻分开。

如果您的网站过去曾同时请求身份验证令牌和授权令牌，那么在使用 Google Identity 服务 JavaScript 库时，您需要调整用户体验，将身份验证时刻与授权时刻分开。

在身份验证时，您的网站可以集成“一键快捷登录”“自动登录”或“使用 Google 账号登录”按钮，以便用户登录或注册您的网站。
在授权时刻，您的网站可以调用授权 API 以获取访问 Google API 或服务的权限和令牌。

为了实现流畅的用户体验转换并降低复杂性，常见做法是将该流程分为两个单独的步骤。

重构用户体验，将身份验证和授权时刻分开。
迁移到 Google Identity 服务 JavaScript 库。

要点：我们将在下文中重点介绍 Authentication Moment API 和相关功能。如需了解授权时刻 API 和功能，请参阅授权 API 文档。

HTML API 与 JavaScript API

您可以使用 HTML API 或 JavaScript API 将“一键式登录”“自动登录”或“使用 Google 账号登录”按钮集成到您的网页中。

借助 HTML API，您可以使用更多内置功能。例如，

在网页加载时呈现“一键登录”或“使用 Google 账号登录”按钮。
在完成一键式登录、自动登录或按钮弹出式窗口/重定向用户体验后，将返回的凭据提交到您的服务器端端点（由 data-login_uri 属性指定）。
通过 double-submit-cookie 防范 CSRF 攻击。
使用代码生成器生成 HTML 代码，然后将其复制到您的 HTML 网页中即可。

借助 HTML API，您还可以编写一些 JavaScript 来自定义行为。

您可以编写自己的回调处理脚本，然后将函数名称设置为 data-callback 属性。一个很好的示例是使用 XmlHttpRequest 将返回的凭据提交到您的服务器，以避免默认的 POST 提交导致页面重新加载。

要点：如需在不重新加载网页的情况下进行身份验证，常见做法是通过 JavaScript 回调处理程序接收 JWT 凭据，然后使用 XmlHttpRequest 将其提交到您的服务器。

使用 JavaScript API，您可以在某些场景中更灵活地操作。

稍后呈现“一键快捷登录”和“使用 Google 账号登录”按钮。例如，在用户从菜单中选择 Login 后。
多次调用 API。例如，每次呈现登录对话框时，都需要呈现“使用 Google 账号登录”按钮。
动态生成 HTML 页面，使得难以在其中嵌入 API 调用代码。
您在很晚之后加载 Google Identity 服务 JavaScript 库。

HTML API 代码只能在网页加载事件或 Google Identity 服务 JavaScript 库加载事件（以较晚者为准）中调用一次。如果 HTML API 行为不符合您的预期，您应使用 JavaScript API。

请勿在同一网页中将 HTML API 与 JavaScript API 搭配使用来初始化网页或进行一键式和按钮渲染。检查您的 HTML 和 JavaScript 代码，看看它们是否可能存在重叠之处。请注意以下几点：

如果您的 HTML 代码中存在 <div id='g_id_onload' ... ><id> 或 <div class='g_id_signin' ...></div> 中的一个或多个元素，则表示您使用的是 HTML API。
如果您的 JavaScript 代码中调用了 initialize()、prompt() 或 render() 中的一个或多个方法，无论这些方法是内嵌的还是从单独的 JavaScript 文件加载的，都表示您在使用 JavaScript API。

以下 JavaScript API 可独立于初始化或一按即达和按钮渲染使用；它们没有对应的 HTML API：

“使用 Google 账号登录”按钮注意事项

本部分介绍了将“使用 Google 账号登录”按钮集成到您的网站中的注意事项。

弹出式窗口与重定向

OAuth 2.0 规范考虑了 HTTP 重定向，但缺少有关呈现弹出式对话框的指导。弹出式窗口用户体验（尤其是在桌面版网络上）可能会为最终用户提供更好的用户体验。这是因为系统不会将用户重定向到第三方网页，并且类似对话框的弹出式窗口可提供上下文相关的权限授予体验。

使用弹出式窗口用户体验时，身份提供程序需要基于客户端跨源通信渠道，将 OAuth 响应从显示身份提供程序意见征求页面的弹出式窗口传递到显示第三方页面的主窗口。通常，需要在两个端使用 JavaScript 代码，才能跨窗口发送和接收 OAuth 响应。

“使用 Google 账号登录”按钮支持弹出式窗口和重定向用户体验。默认情况下，系统会使用弹出式界面。您可以通过设置 data-ux_mode 属性来更改用户体验。

“使用 Google 账号登录”按钮重定向流程与 OAuth 重定向流程之间存在一些差异。

“使用 Google 账号登录”按钮重定向流程始终使用 POST 方法将凭据提交到您的 Web 服务器，而 OAuth 重定向通常使用 GET 方法。
“使用 Google 账号登录”按钮重定向流程提交的参数不同于 OAuth 重定向流程的参数。

对于使用 HTML API 的开发者，无论使用哪种用户体验，凭据始终都会使用 POST 方法和相同的参数提交到 data-login_uri。这样，您就可以在不更改其他代码的情况下切换界面模式。对于重定向用户体验，您必须在 Google API 控制台中将 data-login_uri 添加到客户端的已获授权的重定向 URI 中。

按钮自定义

不支持使用您自己的按钮。没有用于以编程方式启动按钮流的 API。

如需启用“使用 Google 账号登录”按钮流程，您只需在网页上呈现一个或多个“使用 Google 账号登录”按钮即可。当用户点击这些按钮时，系统会透明地启动和处理按钮流程。

借助按钮渲染 API，您可以自定义“使用 Google 账号登录”按钮的外观和风格。建议您使用代码生成器以互动方式设计按钮。即使您使用 JavaScript API，也可以先生成 HTML 代码，然后将代码复制到 JavaScript API 中的相应字段。

没有任何 API 可让网站控制是否应使用个性化信息来呈现按钮。如果满足所有条件，系统就会显示个性化按钮。如需了解详情，请参阅了解“个性化”按钮。

您可以在同一个网页中放置多个按钮。代码生成器每次只能创建一个按钮。您可以多次运行该脚本，并将生成的 <div class='g_id_signin' ...></div> 代码复制到网页中。

按钮呈现最佳实践

出于隐私保护方面的考虑，个性化按钮会显示在 accounts.google.com 网域的 iframe 中。在网络速度缓慢的情况下，加载 iframe 可能需要很长时间。为了缓解此延迟问题，系统会分两个步渲染按钮，如下所示：

内嵌按钮版本会在您网站的 DOM 树中呈现。这只是一个文本按钮，不会使用任何个性化信息。目的是让用户尽快看到该按钮。
系统会向 Google 发送 iframe 请求，以加载可能包含个性化信息的按钮 iframe。按钮 iframe 加载完毕后，系统会移除内嵌版本按钮。

下面列出了一些最佳实践，可最大限度缩短显示“使用 Google 账号登录”按钮流程按钮的延迟时间。

尽早加载 Google Identity 服务 JavaScript 库。考虑在某些其他大型库之前加载 JavaScript 库，尤其是在移动网站上。
如果只有在用户从菜单中选择登录后，系统才会呈现“使用 Google 账号登录”按钮。您可以先在隐藏元素中呈现“使用 Google 账号登录”按钮，然后在用户从菜单中选择登录后使其可见。

要点：尽早加载 Google Identity 服务 JavaScript 库，以最大限度地缩短显示“使用 Google 账号登录”按钮的延迟时间。

一键登录注意事项

自动登录

借助自动登录功能，如果用户之前已向您的网站授予权限，则无需点击“一键登录”提示即可登录您的网站。

可取消的自动登录具有以下优势。

这可能会通过省略一个用户操作来提高登录率。
与之前已废弃的 Google 登录 JavaScript 库提供的静默登录不同，在自动登录时，用户始终会看到一些界面，从而了解他们登录您网站的原因和方式。用户也可以根据需要取消。
它会自动选择用户之前使用的账号，这可能会阻止用户在您的网站上创建重复的账号。

您需要根据网站的用户体验和业务需求来决定是否启用自动登录功能。尤其是在大多数网站退出登录是由会话超时（而非用户明确选择）导致的情况下，自动登录可能是用户恢复会话状态的好方法。

何时显示一键登录界面

使用 HTML API 时，一键式付款始终会在网页加载时显示。借助 JavaScript API，您可以控制“一键式”界面何时显示。请注意，由于以下原因，系统在调用该 API 后可能并不总会显示一键式付款界面。

浏览器中没有任何有效的 Google 会话。
所有有效的 Google 会话均已停用。
正在进行冷却。

请勿尝试仅在按钮点击事件中显示一键式界面。由于所列原因，一键式界面可能无法显示，并且由于用户操作后系统没有显示任何内容，用户可能会获得不佳的用户体验。在按钮点击事件中：

建议

显示包含密码登录和“使用 Google 账号登录”按钮的登录对话框，同时调用 One Tap API。这样可以确保用户始终可以使用某种方法登录您的网站。

不推荐

如果仅提供一键登录，如果系统未显示一键登录，用户可能会遇到登录体验中断的问题。
如果“一键式”功能未显示，请使用界面状态回调显示其他界面。不建议这样做，因为界面状态回调可能无法与未来版本中的联合身份验证管理正常配合使用。

在 ITP 浏览器中一键登录

由于智能反跟踪 (ITP) 机制，常规的“一键式”用户体验无法在 ITP 浏览器（例如 iOS 版 Chrome、Safari 和 Firefox）上使用。这些浏览器上会提供以欢迎页面开头的其他用户体验。

您可以根据需要停用 ITP 浏览器上的一键式体验。如需了解详情，请参阅ITP 浏览器上的一键式支持。

无法在非 ITP 浏览器（例如 Android/macOS/Linux 版 Chrome 和 Edge）上启用此用户体验。

如果用户点击关闭，则取消提示

默认情况下，如果用户点击提示以外的区域，一键式登录提示会自动关闭。您可以根据需要更改此行为。

由于屏幕尺寸足够大，因此建议您在桌面版网站上让“一键式登录”提示保持打开状态。

更改一键式体验的位置

在桌面版网络上，您可以更改“一键式登录”提示的位置。不过，我们不建议使用此功能，因为未来的版本中的联合身份凭据管理功能不支持此功能。

更改登录上下文

一键式付款应是您网站上更大用户体验流程的一部分。默认情况下，One Tap 界面在登录上下文中使用。界面中的语言包含特定字词，例如“登录”。您可以更改上下文属性，以创建其他措辞。您可以选择最适合您用户体验流程的一键式付款标题。

上下文
`signin`	“使用 Google 账号登录”
`signup`	“使用 Google 账号注册”
`use`	“与 Google 账号关联”

监听一键式登录界面状态

为了无缝集成到更大的用户体验流程中，一键式体验功能可以在界面状态发生变化时通知您。不过，未来的联合身份凭据管理版本不支持此功能。

跨子网域一键启用

默认情况下，系统会按来源跟踪一键式登录冷却时间和其他状态。如果您的网站在多个子网域中显示“一键式登录”，您需要在 API 代码中指明这一点。

静态 HTML 网页中的一键式操作

默认情况下，GIS 库会假定您的网页是动态生成的。您的 HTTP 服务器在生成 HTML 代码时会检查用户登录状态。

如果没有用户登录，则应在生成的网页中添加 One Tap HTML 代码，以触发 One Tap，让用户能够登录您的网站。
如果用户已登录，则生成的页面中不应包含 One Tap HTML 代码。

在这种情况下，添加或移除 One Tap HTML API 代码是 Web 服务器的责任。

One Tap HTML API 代码还可以以另一种方式运行，这种方式专为托管大量静态 HTML 内容的网站而设计。您可以随时在静态 HTML 网页中添加 One Tap HTML API 代码，并指定网站中使用的会话 Cookie 名称。

如果会话 Cookie 不存在，系统会触发一键式登录流程。
如果会话 Cookie 存在，系统会跳过一键式登录流程。

在这种情况下，是否触发一键式流程由您的会话 Cookie 状态控制，而不是网页中是否存在一键式 HTML API 代码。

服务器端集成

一键快捷登录、自动登录或“使用 Google 账号登录”按钮用户体验流程完成后，系统会签发 ID 令牌并与您的网站共享。如需对用户进行身份验证，您需要进行一些服务器端更改，以接收和验证 ID 令牌。

用户体验注意事项

通常，您需要在自己的源中添加 HTTP 端点，以便在服务器端处理响应。以下因素可能会影响最终的用户体验。

是触发“一键登录”还是“使用 Google 账号登录”。
使用的是 HTML API 还是 JavaScript API。
是使用登录 URI 还是 JavaScript 回调函数来处理响应。

您获得的实际用户体验如下所述。

对于“使用 Google 账号登录”按钮重定向用户体验模式：
- 无论是使用 HTML API 还是 JavaScript API，您都需要设置登录 URI。由于用户已被重定向到其他网页，因此无法使用 JavaScript 回调函数来处理响应。
- 用户体验摘要：点击“使用 Google 账号登录”按钮后，用户会看到系统将其全页重定向到 Google 界面，以便选择和批准会话。完成后，系统会将整页 POST 提交到您指定的登录 URI。
对于“一键式登录”或“使用 Google 账号登录”按钮弹出式界面用户体验模式，如果使用 JavaScript API，或者使用 HTML API 并提供 JavaScript 回调函数，请执行以下操作：
- 系统会将身份验证响应传递回 JavaScript 回调函数。
- 用户体验摘要：系统会在网页上方显示“一键式”提示或弹出式窗口。用户在提示或弹出式窗口中完成会话选择和批准的用户体验后，JavaScript 回调函数会收到响应。后续的用户体验取决于回调函数向服务器提交响应的方式。
要点：如需在不重新加载网页的情况下进行身份验证，常见做法是通过 JavaScript 回调函数接收身份验证响应，然后使用 XmlHttpRequest 将其提交到服务器。
要点：如需强制执行您自己的安全措施，您可以通过 JavaScript 回调函数接收身份验证响应，然后将其与您的网站所需的其他参数一起提交。
否则（使用登录 URI 的 HTML API 情形）：
- 系统会将授权响应提交到登录 URI。
- 用户体验摘要：系统会在网页上方显示“一键式”提示或弹出式窗口。用户在提示或弹出式窗口中完成会话选择和批准的用户体验后，系统会使用全页 POST 提交功能将授权响应提交到您指定的登录网址。

建议您使用一致的方式提交“一键式登录”回答和“使用 Google 账号登录”按钮回答。

安全注意事项

如需防范跨站请求伪造攻击，请执行以下操作：

对于由 Google Identity Service 客户端 JavaScript 库触发的提交操作，您可以使用内置的双重提交 Cookie 模式。如需了解详情，请参阅在服务器端验证 Google ID 令牌。
如需使用 XmlHttpRequest 提交到您自己的来源，您可以使用自定义 HTTP 标头或安全团队批准的其他安全措施。

如需验证身份验证响应中的 ID 令牌，强烈建议您使用适用于您平台的 Google API 客户端库或通用 JWT 库。

常见问题解答 (FAQ)

WebView 中是否支持一键登录和“使用 Google 账号登录”按钮？

不可以。出于安全考虑，用户不应将 Google 会话添加到 WebView。因此，由于 Webview 中不应存在任何 Google 会话，因此 GIS 在 Webview 中处于停用状态。
我可以使用自己的“使用 Google 账号登录”按钮吗？不可以。使用 OAuth 服务器端流程或较低版本的 Google 登录 JavaScript 库时，依赖方可以使用登录品牌推广指南构建自己的 Google 登录按钮版本。

不过，“使用 Google 账号登录”已移除此功能。所有“使用 Google 账号登录”按钮都必须由 Google Identity 服务 JavaScript 库生成。之所以做出这样的调整，原因有两个。
- 一些依赖方未遵循相关准则，导致各个网站上的“使用 Google 账号登录”按钮不一致。
- 通过库生成资源后，当登录品牌推广指南本身发生变化时，您无需进行任何更改。
为了强制执行此规则，JavaScript 库仅公开用于呈现按钮的 API，而未公开用于启动登录流程的 API。
如果我的网站仅启用了“一键登录”，但未启用“使用 Google 账号登录”按钮，该怎么办？

建议您在网站上同时使用“一键登录”和“使用 Google 账号登录”按钮。由于指数级冷却，系统可能不会每次都显示“一键式付款”。如果用户确实想使用 Google 账号登录您的网站，可以前往您的主要登录对话框，然后使用其中的“使用 Google 账号登录”按钮登录。使用“使用 Google 账号登录”按钮成功登录后，系统会清除“一键式登录”冷却状态，以便在下次登录时显示“一键式登录”。Google 的其他按钮流程无法清除一键式启动冷却状态，因为它们位于不同的 JavaScript 二进制文件中。

如果您的网站仅启用了“一键式登录”，而未启用“使用 Google 账号登录”按钮，则由于指数级冷却状态未及时清除，您的“一键式登录”流程的效果可能会下降。
我的 HTML API 代码何时会被解析？我可以稍后更改 HTML API 代码吗？

Google Identity Services JavaScript 库会在 JavaScript 库加载事件或 DomContentLoaded 事件（以较晚者为准）解析和执行您的 HTML API 代码。
- 如果在加载 JavaScript 库时触发 DomContentLoaded 事件，系统会立即解析并执行您的 HTML API 代码。
- 否则，JavaScript 库会为 DomContentLoaded 事件添加监听器。触发后，监听器会解析并执行您的 HTML API 代码。
另请注意，HTML API 代码的解析和执行是一次性的。
- 解析和执行完成后，系统会忽略对 HTML API 代码进行的任何后续更改。
- 没有任何 API 可供开发者触发解析或执行流程。
提示：如果上述行为不符合您的要求，请使用 JavaScript API。