集成注意事项

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

“使用 Google 帐号登录”摘要

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

1. 用户登录 Google 网站。

   若要让“使用 Google 帐号登录”功能正常运行，浏览器中应该有一个活跃的 Google 会话。仅当用户在加载您的网页之前已经登录 Google 时，才会触发一键快捷登录和自动登录。对于“使用 Google 帐号登录”按钮流程，此步骤是可选的，因为系统会在用户按下该按钮时提示用户登录 Google。

   要点 ：出于安全考虑，不允许在 iframe 中添加新的 Google 会话。

2. 用户浏览嵌入了一键快捷功能、自动登录或“使用 Google 帐号登录”按钮的网页。

   要点 ：您可以使用代码生成器轻松生成代码，以将“一键式”“自动登录”和“使用 Google 帐号登录”按钮嵌入到您的网页中。

3. 用户与“一键登录”按钮、“使用 Google 帐号登录”按钮及后续用户体验流程互动，以便：

   • 请选择一个有效的 Google 会话以继续。
   • 征得最终用户的同意，以便与您的网站共享个人资料信息（如果尚未表示同意）。
   要点：仅当之前只有一个 Google 活跃会话已授予该权限，并且您的网站启用了该功能时，才会发生自动登录。
   注意：自动登录仅适用于一键式用户体验，而不适用于“使用 Google 帐号登录”按钮用户体验。

   如果浏览器中只有一个处于活动状态的 Google 会话，

   • 一键快捷功能会自动选择唯一的会话，因此会跳过帐号选择器页面。
   • “使用 Google 帐号登录”按钮会保留在帐号选择器页面上，以便用户在需要时添加新的 Google 会话。

   如果所选 Google 帐号之前未用于您的网站，或者权限已被撤消，系统会显示意见征求页面。

   

   获得批准后，Google 将记录该决定，以便下次跳过意见征求页面。

4. 系统会使用 JavaScript 回调处理程序或提交到您的后端服务的帖子共享包含用户姓名、电子邮件地址和个人资料照片的 JSON Web 令牌（也称为 ID 令牌）凭据。

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

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

5. 在服务器端，系统会验证并使用 Google 发放的 JWT 凭据，以创建新帐号或在您的网站上建立经过身份验证的会话。

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

   用户的 Google 帐号登录状态和您的应用相互独立，但在您知道用户已成功通过身份验证并登录其 Google 帐号登录的那一刻除外。在您的网站上保持已登录状态的活跃会话的同时，用户可能会保持登录状态、退出登录或切换到其他 Google 帐号。

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

访问 Google API 和服务

虽然您已集成身份验证 API（如上所述），但如果您的网站需要代表经过身份验证的用户访问 Google API 和服务，您可能也需要集成 authorization API。身份验证可为您的网站提供 ID 令牌以对用户进行身份验证，而授权可为您的网站提供（单独的）访问令牌以及使用 Google API 和服务的权限。如需了解详情，请参阅进行 Web 授权。

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

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

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

• 在进行身份验证时，您的网站可以与一键快捷功能、自动登录或“使用 Google 帐号登录”按钮集成，让用户能够登录或注册您的网站。
• 在授权时，您的网站可以调用授权 API 来获取访问 Google API 或服务的权限和令牌。

为了顺利实现用户体验过渡并降低复杂性，常见做法是将此过程划分为两个单独的步骤。

1. 重构用户体验，将身份验证和授权时刻分开。

2. 迁移到 Google Identity 服务 JavaScript 库。

   要点 ：之后我们将重点介绍身份验证时刻 API 和功能。如需了解授权时刻 API 和功能，请参阅 Authorization 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 将返回的凭据提交给您的服务器，以避免因默认提交后而导致页面重新加载。

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

利用 JavaScript API，您可以更灵活地处理如下某些情况。

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

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

注意 ：我们建议您尽可能使用 HTML 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。

警告 ：在同一网页中同时使用 HTML API 和 JavaScript API 来初始化网页或一键呈现和按钮呈现可能会导致一些棘手的错误，例如“一键快捷”按钮和按钮呈现两次。

以下 JavaScript API 可独立于初始化或一键呈现和按钮呈现使用；这些 API 没有对应的 HTML API：

• revoke
• cancel
• disableAutoSelect
• storeCredential

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

弹出式窗口与重定向

OAuth 2.0 规范考虑了 HTTP 重定向，但缺乏关于呈现弹出式对话框的指导。弹出式用户体验（尤其是在桌面版网站上）可以为最终用户提供更好的用户体验。这是因为用户不会被重定向离开第三方页面，而类似对话框的弹出式窗口提供了权限授予的上下文体验。

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

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

要点 ：“使用 Google 帐号登录”按钮支持弹出式用户体验。

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

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

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

要点 ：请注意“使用 Google 帐号登录”按钮重定向流程与 OAuth 重定向流程之间的区别。

按钮自定义

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

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

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

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

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

警告 ：同一网页中只能有一个 <div id='g_id_onload' ... ><id> 元素。请勿将多个 g_id_onload 元素复制到您的网页中。

按钮渲染最佳实践

出于隐私原因，个性化按钮会显示在来自 accounts.google.com 网域的 iframe 中。在网速较慢时，加载 iframe 可能非常耗时。为了缓解这种延迟问题，按钮会分 2 个步骤呈现，如下所示：

1. 内嵌按钮版本在您网站的 DOM 树中呈现。它只是一个文字按钮，无法使用个性化信息。这样做的目的是让用户能够尽快看到该按钮。
2. 系统会向 Google 发送 iframe 请求，以便加载按钮 iframe，其中可能包含个性化信息。按钮 iframe 加载后，内嵌版本按钮会被移除。

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

• 尽早加载 Google Identity 服务 JavaScript 库。 建议先加载 JavaScript 库，然后再加载其他大型库，尤其是在移动网站上。

• 仅当用户从菜单中选择登录后，系统才会显示“使用 Google 帐号登录”按钮。您可以先在隐藏元素中呈现“使用 Google 帐号登录”按钮，然后在用户从菜单中选择登录后将其显示出来。

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

一键快捷功能注意事项

自动登录

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

• 它或许能通过保存一项用户操作来提高登录率。
• 与之前已废弃的 Google 登录 JavaScript 库中提供的静默登录不同，自动登录时，用户始终会看到某个界面，该界面让用户了解登录网站的原因和方式。用户也可以根据需要取消订阅。
• 它会自动选择用户之前使用的帐号，以防用户在您的网站上创建重复帐号。

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

何时显示一键式界面

使用 HTML API，“一键快捷”功能始终在网页加载时显示。使用 JavaScript

因此，您可以控制一键式界面何时显示。请注意，由于下述某些原因，在调用该 API 后，系统不一定会显示一键式界面。

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

请勿尝试针对按钮点击事件仅显示一键式界面。一键式界面可能会因上述原因无法显示，并且用户可能会因为用户操作后未显示任何内容，导致用户体验不佳。在按钮点击事件发生时：

建议

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

不推荐

• 如果仅提供一键快捷功能，如果未显示一键快捷功能，用户可能会无法登录。
• 使用界面状态回调，在一键未显示的情况下显示另一个界面。我们不建议这样做，因为未来版本中界面状态回调可能无法与联合凭据管理配合使用。

ITP 浏览器一键开启

由于智能反跟踪 (ITP) 的缘故，普通的一键式用户体验在 ITP 浏览器（如 iOS 版 Chrome、Safari 和 Firefox）上不起作用。这些浏览器提供了以欢迎页面开头的不同用户体验。

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

注意 ：ITP 浏览器上的一键式用户体验不支持自动登录。

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

如果用户点击离开，则取消提示

默认情况下，如果用户在一键输入提示之外点击提示，则会自动关闭。您可以根据需要更改此行为。

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

注意 ：如果用户因点击“使用 Google 帐号登录”按钮而打开了一个弹出式窗口，那么同一页面上的“一键登录”界面会关闭，以避免同时向用户显示两个正在进行的“使用 Google 帐号登录”用户体验流程。此行为不受上述取消设置的影响。

更改一键式用户体验的位置

在桌面版网站上，您可以更改一键快捷提示的位置。 但是，我们不推荐使用此功能，因为在未来版本中，联合凭据管理将不支持此功能。

警告 ：如果您更改了一键式提示的位置，那么在未来的版本中，当一键快捷功能集成预期联合凭据管理功能时，您可能需要对代码或界面进行一些更改。

更改登录环境

一键快捷功能应该成为您网站上更大的用户体验流程的一部分。默认情况下，系统会在登录上下文中使用一键式界面。界面中的语言包含特定的措辞，例如“登录”。您可以更改上下文属性以创建一组不同的措辞。您可以选择一个最适合您的用户体验流程的一键式标头。

上下文
signin	“使用 Google 帐号登录”
signup	“通过 Google 注册”
use	“通过 Google 使用”

要点 ：如需了解如何更改上下文，请参阅更改一键登录上下文。

监听一键式界面状态

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

警告 ：如果您监听显示状态的一键式界面，当一键采纳联合凭据管理功能在未来版本中，您可能需要对代码或界面进行一些更改。

一键跨子网域

默认情况下，系统会按源跟踪一键式冷却期和其他状态。如果您的网站在多个子网域中显示一键快捷功能，您需要在 API 代码中指明这一点。

要点 ：如需了解详情，请参阅跨子网域显示一键快捷功能。

点按一次在静态 HTML 页面中

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

• 如果没有用户登录，则应在结果页面中加入一键式 HTML 代码，以便触发一键快捷功能，让用户登录您的网站。
• 如果用户已登录，则生成的页面中不应包含一键式 HTML 代码。

在这种情况下，您的网络服务器需要负责添加或移除一键式 HTML API 代码。

一键式 HTML API 代码可以以其他方式运行，此方式专为托管大量静态 HTML 内容的网站而设计。您始终可以在静态 HTML 网页中添加一键式 HTML API 代码，并指定您的网站中使用的会话 Cookie 名称。

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

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

要点：如需了解详情，请参阅使用 Cookie 切换一键式显示界面。

要点：您无法切换使用 Cookie 呈现的“使用 Google 帐号登录”按钮，因为它通常用在您的主登录对话框（而不是内容页面）中。

服务器端集成

在完成一键式自动登录或“使用 Google 帐号登录”按钮用户体验流程后，系统会颁发 ID 令牌并将其分享给您的网站。为了对用户进行身份验证，需要进行一些服务器端更改，才能接收和验证 ID 令牌。

用户体验注意事项

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

• 是触发了一键快捷功能还是“使用 Google 帐号登录”功能。
• 使用 HTML API 还是 JavaScript API。
• 指定是使用登录 URI 还是 JavaScript 回调函数来处理响应。

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

1. 对于“使用 Google 帐号登录”按钮重定向用户体验模式：

   • 无论使用 HTML API 还是 JavaScript API，您都需要设置登录 URI。由于用户已经离开您的网页，因此无法使用 JavaScript 回调函数处理响应。
   • 用户体验摘要：在点击“使用 Google 帐号登录”按钮后，用户会看到重定向到 Google 界面的整页重定向，以便用户选择和审批会话。完成后，系统会将整页的 POST 提交到您指定的登录 URI。

2. 对于“一键快捷”按钮或“使用 Google 帐号登录”按钮弹出式用户体验模式，如果您使用 JavaScript API，或使用 HTML API 且提供了 JavaScript 回调函数：

   • 身份验证响应将传回 JavaScript 回调函数。
   • 用户体验摘要：您的网页上方会显示一键式提示或弹出式窗口。当用户在提示或弹出式窗口中完成用户体验，以进行会话选择和批准后，JavaScript 回调函数就会收到响应。后续用户体验取决于回调函数向服务器提交响应的方式。
   要点：如需在不重新加载网页的情况下进行身份验证，一种常见做法是通过 JavaScript 回调函数接收身份验证响应，然后通过 XmlHttpRequest 将其提交到您的服务器。
   要点：为了强制执行您自己的安全措施，您可以通过 JavaScript 回调函数接收身份验证响应，然后使用网站要求的其他参数提交这些响应。

3. 否则（采用登录 URI 大小写的 HTML API）：

   • 身份验证响应会提交到登录 URI。
   • 用户体验摘要：您的网页上方会显示一键式提示或弹出式窗口。用户在提示或弹出式窗口中完成会话选择和批准的用户体验后，会通过整页的 POST 提交方式，将身份验证响应提交到您指定的登录网址。

建议您以一致的方式提交一键快捷响应和“使用 Google 帐号登录”按钮响应。

安全注意事项

为防止跨站请求伪造攻击，

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

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

常见问题解答 (FAQ)

• WebView 中是否提供“一键登录”按钮和“使用 Google 帐号登录”按钮？

  不可以。出于安全考虑，用户不应将 Google 会话添加到网页视图中。因此，在 WebView 中，GIS 会被停用，因为其中应该没有 Google 会话。

• 我可以使用自己的“使用 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 服务 JavaScript 库会在 JavaScript 库加载事件或 DomContent 加载事件（以较晚者为准）解析并执行您的 HTML API 代码。

  • 如果在加载 JavaScript 库时触发了 DomContent 加载事件，系统会立即解析并执行 HTML API 代码。
  • 否则，JavaScript 库就会为 DomContent 加载事件添加一个监听器。触发后，监听器会解析并执行 HTML API 代码。

  另请注意，HTML API 代码的解析和执行是一次性的。

  • 解析和执行后，对 HTML API 代码所做的任何后续更改都会被忽略。
  • 没有任何可供开发者触发解析或执行过程的 API。
  提示 ：如果上述行为不符合您的要求，请使用 JavaScript API。