集成注意事项

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

“使用 Google 账号登录”摘要

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

  1. 用户登录 Google 网站。

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

  2. 用户浏览您嵌入了一键式、自动登录或“使用 Google 账号登录”按钮的网页。

  3. 用户可以与一键快捷功能、“使用 Google 账号登录”按钮和后续用户体验流程进行互动，以便：

    • 选择一个活跃的 Google 会话以继续操作。
    • 征得最终用户同意，以便与您的网站共享个人资料信息（如果尚未同意）。

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

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

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

    “使用 Google 账号登录”按钮同意声明

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

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

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

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

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

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

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

访问 Google API 和服务

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

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

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

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

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

为了顺利完成用户体验过渡并降低复杂性，常见做法是将该过程分成两个独立的步骤。

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

  2. 请迁移到 Google Identity Services JavaScript 库。

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 API，您可以更灵活地处理某些场景，如下所示。

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

HTML API 代码只能在网页加载事件或 Google Identity 服务 JavaScript 库 onload 事件中调用一次，以较晚者为准。如果 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 可以独立于初始化或一键式呈现和按钮呈现使用；这些 API 没有对应的 HTML API：

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

弹出式窗口与重定向

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

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

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

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

  • “使用 Google 账号登录”按钮重定向流程始终使用 POST 方法将凭据提交到您的网络服务器，而 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 可能非常耗时。为了缓解此延迟问题，按钮分 2 步呈现，如下所示：

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

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

  • 请尽早加载 Google Identity Services JavaScript 库。 请考虑先加载 JavaScript 库，然后再加载其他大型库，尤其是在移动网站上。

  • 仅当用户从菜单中选择登录后，系统才会显示“使用 Google 账号登录”按钮。您可以先在隐藏元素中呈现“使用 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）上启用此用户体验。

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

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

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

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

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

更改登录上下文

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

上下文
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 代码。

服务器端集成

一键快捷功能完成自动登录或“使用 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 回调函数会接收响应。后续用户体验取决于回调函数向服务器提交响应的方式。

  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 中。这样一来，WebView 中就不会存在 Google 会话，因此会在 WebView 中停用 GIS。

  • 我可以使用自己的 Google 账号登录按钮吗？不需要。通过 OAuth 服务器端流程或早期版本的 Google 登录 JavaScript 库，依赖方能够根据登录品牌推广指南来构建自己的 Google 登录按钮版本。

    不过，“使用 Google 账号登录”功能已移除此功能。所有“使用 Google 账号登录”按钮都必须由 Google Identity Services JavaScript 库生成。这种变化有两个原因。

    • 一些依赖方未能遵循该准则，这会导致“使用 Google 账号登录”按钮在各个网站上不一致。
    • 通过由库生成，当登录品牌推广指南本身发生更改时，您无需进行任何更改。

    为了强制执行此规则，JavaScript 库仅公开用于呈现按钮的 API，而不公开用于启动登录流程的 API。

  • 如果我的网站仅支持一键快捷功能，而不支持“使用 Google 账号登录”按钮，该怎么办？

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

    如果您的网站仅启用了“使用 Google 帐号登录”按钮，而没有启用“使用 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。