通过 iframe 集成一键快捷功能

Google One 点按可在您自己的网站托管的 iframe(以下简称“中间 iframe”)内呈现。使用中间 iframe 时,一键式用户体验没有任何明显的改变。

基于 iframe 的中级集成带来了一些灵活性和风险:

  • 一键式嵌入式用户体验和后续用户体验流程

    完成一键式用户体验后,您可以在中间 iframe 内显示后续的用户体验流程。因此,一键式体验和后续用户体验可以嵌入到当前内容页面中。以下是一个示例。

    具有中间 iframe 的嵌入式用户体验示例。

    如果没有中间 iframe,通常需要进行整页导航以显示后续用户体验流程,这在某些情况下可能会造成干扰。

  • 一次集成,到处展示

    所有一键式集成代码(One Tap API 调用和后续用户体验处理)均封装在中间 iframe 中。在可能显示“一键恢复”功能的内容页面上,您只需嵌入中间 iframe 即可。

    这种架构可将关注点分离,从而降低集成和维护成本。

  • 限制 ID 令牌曝光范围

    ID 令牌直接由中间 iframe 使用。它们从不会向内容页面公开。此架构可能会大幅缩小 ID 令牌的公开范围。

    中间 iframe 方法也非常适合已有专用登录相关子网域(例如,login.example.com)和多个内容相关子网域(例如,sports.example.com 和 games.example.com)的网站。

  • 一键式显示网域

    根据 Google OAuth 政策的要求,所有接收 OAuth 响应的网域都需要在 Google API 控制台中预注册。通过常规的“一键集成”功能,开发者需要预注册“一键快捷功能”可能会显示的所有网域,因为 ID 令牌将传回这些网域。某些网站允许用户动态创建子网域,而这些预注册无法实现。因此,这些动态创建的子网域中无法显示“一键恢复”按钮。

    此问题可通过利用中间 iframe 来解决。在这种情况下,只需要预注册中间 iframe 的网域。您无需注册内容页面网域,因为 ID 令牌不会提供给这些内容页面。

  • AMP 支持

    默认情况下,Google One Tap 无法在 AMP 网页中显示,原因如下。

    1. 不允许使用自定义 JS 库或代码。

    2. AMP 缓存可能会以另一个(AMP 查看工具)网域呈现网页。

    此问题可通过利用中间 iframe 架构解决。在中间 iframe 中完成一键式集成后,开发者可以通过添加 <amp-onetap-google> 组件,将其嵌入到 AMP 网页中。

    AMP 网页和非 AMP HTML 网页可以重复使用相同的中间 iframe。

  • 隐私权风险

    开发者必须采取措施,防止将中间 iframe 嵌入到意外网域中。例如,恶意.com 可能会嵌入您的中间 iframe,从而导致该网站在一键式体验中停止展示。这肯定会导致最终用户在隐私方面面临许多问题。

  • 安全风险

    由于存在上述意外框架问题,您的中间 iframe 绝不能向父级框架发送安全或隐私敏感数据,例如 ID 令牌、会话 Cookie 值、用户数据等。如果不遵守此规则,可能会导致您的网站面临危险。

在中间 iframe 中一键渲染

如需在中间 iframe 内显示“一键点击”,请将以下代码段放在中间 iframe 的 HTML 代码中:

<div id="g_id_onload"
     data-client_id="YOUR_GOOGLE_CLIENT_ID"
     data-login_uri="https://your.domain/your_login_endpoint"
     data-allowed_parent_origin="https://example.com">
</div>

如果存在 data-allowed_parent_origin 属性,Google One 点按将在中间 iframe 模式下运行。您可以将一个网域或以英文逗号分隔的网域列表设置为属性值。同时也支持通配符子网域。

(可选)在中间 iframe 中呈现后续用户体验

在登录响应中,您可以返回任何 HTML 代码,这些代码可能会向最终用户显示一些可见内容。例如,请求提供额外的个人资料信息,或同意服务条款 (TOS) 等。提交网页后,您可以显示更多网页。例如,付款或订阅等。

您还可以选择调整中间 iframe 的大小,如下所示。

<script src="https://accounts.google.com/gsi/intermediatesupport"></script>
<script>
  google.accounts.id.intermediate.notifyParentResize(320);
</script>

总的来说,借助中间 iframe,可以将完整登录或注册用户体验流程实现为嵌入式用户体验。

对于一键式用户体验后的第一个页面,您需要调用 notifyParentResize() 方法两次,原因如下。

  1. 完成一键式用户体验后,中间 iframe 会设为隐藏。

  2. 隐藏元素的 offsetHeight 属性值为 0。

在第一次调用中,您可以将 iframe 高度调整为 1px,使其可见。然后,在 offsetHeight 属性值可用后,您可以将其大小调整为合适的高度。

以下示例代码展示了如何在点按一次用户体验后验证界面的父级 iframe 并调整界面的中间 iframe 的大小。

<script>
    window.onload = () => {
      google.accounts.id.intermediate.verifyParentOrigin(
          ["https://example.com","https://example-com.cdn.ampproject.org"],
          () => {
            google.accounts.id.intermediate.notifyParentResize(1);
            window.setTimeout(() => {
              let h = document.getElementById('container').offsetHeight;
              google.accounts.id.intermediate.notifyParentResize(h);
            }, 200);
          },
          () => {
            document.getElementById('container').style.display = 'none';
            document.getElementById('warning').innerText =
                'Warning: the page is displayed in an unexpected domain!';
          }
      );
    };
</script>

移除完成用户体验的中间 iframe

用户体验流程完成后,您必须通知父内容页面移除中间 iframe。为此,您可以将以下代码段放置在登录响应代码中。

<script src="https://accounts.google.com/gsi/intermediatesupport"></script>
<script>
  google.accounts.id.intermediate.notifyParentDone();
</script>

如果跳过用户体验流程,需要改为调用 notifyParentClose 方法。

将中间 iframe 嵌入到 HTML 网页中

将以下代码段放置在您希望 Google 一键展示的所有 HTML 页面中:

<script src="https://accounts.google.com/gsi/intermediate"></script>
...
<div id="g_id_intermediate_iframe"
        data-src = "https://example.com/onetap_iframe.html">
</div>

data-src 属性是中间 iframe 的 URI。