首页

首页是 Google Workspace 加购服务的一项功能，可用于定义一个或多个非情境化卡片。非情境化卡片会在用户处于特定情境之外时显示用户界面，例如在查看 Gmail 收件箱时未打开任何邮件或草稿。

借助首页，您可以显示非情境相关的内容，类似于快速访问侧边栏（Google Keep、Google 日历和 Google Tasks）中的 Google 应用。首页还可以在用户首次打开插件时提供初始起点，有助于教导新用户如何与插件互动。

通过在项目清单中指定插件的主页并实现一个或多个 homepageTrigger 函数（请参阅主页配置），为插件定义主页。如果您的插件扩展了 Google Chat，其首页会显示在与 Chat 应用的 1 对 1 私信的首页标签页中，并且会在 Google Cloud 控制台中进行配置，而不是在清单中进行配置（请参阅为 Chat 配置首页）。

您可以拥有多个首页，每个首页对应一个插件所扩展的主机应用。您还可以定义一个通用默认首页，用于未指定自定义首页的主机。

在以下情况下，系统会显示插件首页：

  • 当在宿主中首次打开该插件（在授权后），或者当用户在 Chat 中与您的 Chat 应用进行一对一私信时打开首页标签页时。
  • 当用户在插件处于打开状态时从情境化上下文切换到非情境化上下文时。例如，从修改日历活动到主日历。
  • 当用户点击返回按钮的次数足以从内部堆栈中弹出所有其他卡片时。
  • 当非情境卡片中的界面互动导致 Navigation.popToRoot 调用时。

建议设计首页。如果您未定义任何卡片，则每当用户前往首页时，系统都会使用包含插件名称的通用卡片。

首页配置

Google Workspace 加载项使用 addOns.common.homepageTrigger 字段在加载项清单中为宿主应用配置默认首页（非情境化）加载项内容：

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

  • runFunction：Google Workspace 插件框架调用以呈现首页插件卡片的 Google Apps 脚本函数的名称。 此函数是首页触发函数。此函数必须构建并返回一个由 Card 对象组成的数组，这些对象构成了首页界面。如果返回了多张卡片，宿主应用会以列表形式显示卡片标题，供用户从中选择（请参阅返回多张卡片）。

  • enabled：是否应为此范围启用首页卡片。此字段是可选字段，默认值为 true。将此值设置为 false 会导致所有主机的首页卡片都被停用（除非针对相应主机进行了替换；请参阅特定于主机的配置）。

如需让宿主使用通用首页，插件清单中必须同时包含 addOns.common.homepageTrigger 和宿主的顶级资源。例如，如果清单中没有 addOns.gmail，则该插件在 Gmail 中处于停用状态，并且不会在该宿主中显示首页或其他功能。

除了通用配置之外，每个宿主应用的配置中还提供了结构相同的按宿主替换项，位于 addOns.gmail.homepageTrigger、addOns.calendar.homepageTrigger 和其他宿主专用触发器中。

以下示例展示了一个清单，其中定义了一个通用的首页触发器，但该触发器被日历和云端硬盘的自定义函数替换，并针对 Gmail 停用。在此配置中，通用 buildHomePage 函数永远不会执行，因为该函数要么被替换，要么主机被停用。

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

以下清单摘录与上一个示例等效，即使省略了默认 homepageTrigger 和 Gmail 配置也是如此：

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

所有 homepageTrigger 部分都不是必需的。主机产品中插件的界面取决于是否存在相应的清单字段以及是否存在关联的 homepageTrigger。以下示例展示了在不同清单配置下，哪些插件触发器函数会执行以创建首页界面：

图表：显示插件首页触发器函数执行流程

为 Chat 配置主页

与 Google Workspace 的其他宿主应用不同，扩展 Chat 的插件不会在右侧的快速访问面板中显示首页，也不会在清单中使用 addOns.common.homepageTrigger。 Chat 会在与 Chat 应用的 1 对 1 私信的首页标签页中以卡片形式显示您的首页。

如需在 Google Cloud 控制台中为 Chat 加载项启用和配置应用首页触发器，请执行以下操作：

  1. 在 Google Cloud 控制台中，依次前往菜单 > API 和服务 > 已启用的 API 和服务 > Google Chat API > 配置。

    前往 Google Chat API 配置

  2. 在互动功能下，确保启用互动功能处于开启状态，然后选中支持应用主屏幕复选框。

  3. 在连接设置 > 触发器下，根据插件架构在应用首页字段中指定应用首页处理程序：

    • HTTP：输入处理应用首页请求的 HTTPS 端点网址（或将其留空，以便您的通用 HTTP 端点网址接收所有事件）。
    • Google Apps 脚本：输入用于构建和返回首页卡片的 Google Apps 脚本回调函数的名称（默认为 onAppHome）。

  4. 点击保存。

当用户打开与 Chat 应用的私信的首页标签页时，Chat 会向您的端点或函数发送应用首页触发事件。如需呈现首页，请返回一个包含 pushCard 导航操作的 RenderActions 对象（或在更新首页以响应首页卡片中的按钮点击操作时使用 updateCard）：

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps 脚本

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

如需详细了解如何处理 Chat 触发器和返回操作，请参阅接收和响应用户互动。

首页事件对象

调用时，首页触发函数 (runFunction) 或前面所述的应用首页端点会传递一个包含调用上下文数据的事件对象。

首页事件对象不包含 widget 或上下文信息。传递的信息包括以下通用事件对象字段：

  • commonEventObject.clientPlatform
  • commonEventObject.hostApp
  • commonEventObject.userLocale 和 commonEventObject.userTimezone（如需了解限制信息，请参阅访问用户语言区域和时区）。

在 Chat 中，“应用首页”事件对象还包含 chat 字段，其中包含有关用户和互动时间的信息：

  • chat.user：打开首页标签页的 Chat 用户。
  • chat.eventTime：用户打开首页标签页时的时间戳。

如需了解详情，请参阅事件对象。

其他非情境化卡片

您的插件界面可以包含其他非情境化卡片，这些卡片不是首页。例如，您的首页可能有一个按钮，用于打开“设置”卡片以调整插件设置（此类设置通常与上下文无关）。

非情境卡片的构建方式与任何其他卡片一样；唯一的区别在于生成和显示卡片的动作或事件。如需详细了解如何创建卡片之间的过渡效果，请参阅导航方法。