通过 iframe 集成一键快捷功能

Google One Tap 可在您自己的网站托管的 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 嵌入到意外的网域。例如，omcom.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 Tap 将在中间 iframe 模式下运行。您可以将一个网域或以英文逗号分隔的网域列表设置为属性值。也支持通配符子网域。

（可选）在中间 iframe 中呈现后续用户体验

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

您还可以选择调整中间 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 高度调整为 1 像素，使其清晰可见。然后，在 offsetHeight 属性值可用后，您可以将其大小调整为合适的高度。

以下示例代码展示了如何在一键用户体验后验证界面的父来源并调整界面的中间 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。