此页面由 Cloud Translation API 翻译。

为 Google Chat 应用构建首页

本页介绍了如何使用 Google Chat 应用构建私信首页。首页（在 Google Chat API 中称为应用首页）是一种可自定义的卡片界面，会显示在用户与 Chat 应用之间的私信聊天室的首页标签页中。

包含两个 widget 的应用首页卡片。 — **图 1**：显示在与 Chat 应用的私信中的首页示例。

您可以使用应用首页分享与 Chat 应用互动或让用户通过 Chat 访问和使用外部服务或工具的提示。

使用卡片制作工具设计和预览 Chat 应用的消息和界面：

打开卡片制作工具

前提条件

Node.js

一款已启用互动功能的 Google Chat 应用。要创建交互式 Chat 应用，请完成此快速入门。

Python

启用了交互功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。

Java

一款已启用互动功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。

Apps 脚本

启用了交互功能的 Google Chat 应用。如需在 Apps 脚本中创建交互式 Chat 应用，请完成此快速入门。

为 Chat 应用配置应用主屏幕

如需支持应用首页，您必须将 Chat 应用配置为接收 APP_HOME 互动事件。每当用户通过 Chat 应用的私信点击首页标签页时，Chat 应用都会收到此事件。

如需在 Google Cloud 控制台中更新配置设置，请执行以下操作：

在 Google Cloud 控制台中，点击菜单 > 更多产品 > Google Workspace > 产品库 > Google Chat API。

前往 Google Chat API
点击管理，然后点击配置标签页。
在互动功能下，前往功能部分配置应用主屏幕：
1. 选中接收 1 对 1 消息复选框。
2. 选中支持应用主屏幕复选框。
如果您的 Chat 应用使用 HTTP 服务，请转到 连接设置，并为 App Home 网址 字段。您可以使用在 HTTP 端点网址字段。
点击保存。

构建应用首页卡片

当用户打开应用主屏幕时，您的 Chat 应用必须处理 APP_HOME 互动事件。 RenderActions 具有 pushCard 导航和 Card。为了打造互动式体验，卡片可以包含互动式 widget，例如按钮或文本输入，Chat 应用可以处理这些 widget 并通过其他卡片或对话框做出回应。

在以下示例中，Chat 应用会显示初始应用首页卡片，其中显示了卡片的创建时间和一个按钮。当用户点击该按钮时，Chat 应用会返回更新后的卡片，其中会显示更新后的卡片创建时间。

Node.js

node/app-home/index.js

在 GitHub 上查看

app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py

在 GitHub 上查看

@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

在 GitHub 上查看

/**
 * Process Google Chat events
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

Apps 脚本

实现在所有 APP_HOME 互动事件之后调用的 onAppHome 函数：

此示例通过返回卡片 JSON 来发送卡片消息。您还可以使用 Apps 脚本卡片服务。

apps-script/app-home/app-home.gs

在 GitHub 上查看

/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

响应应用主屏幕互动

如果初始应用首页卡片包含按钮等交互式微件或选择输入，您的 Chat 应用必须处理来检索相关互动事件 RenderActions updateCard导航。详细了解如何处理小程序，请参见处理用户输入的信息。

在上一个示例中，初始应用首页卡片包含一个按钮。任何时候用户点击该按钮时，CARD_CLICKED 互动事件触发函数 updateAppHome 以刷新应用首页卡片，如下所示如以下代码所示：

Node.js

node/app-home/index.js

在 GitHub 上查看

// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py

在 GitHub 上查看

def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

在 GitHub 上查看

// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

Apps 脚本

此示例通过返回卡片 JSON 来发送卡片消息。您还可以使用 Apps Script 卡片服务。

apps-script/app-home/app-home.gs

在 GitHub 上查看

/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

打开对话框

Chat 应用还可以通过打开对话框来响应应用首页中的互动。

一个包含各种不同 widget 的对话框。 — **图 3**：提示用户添加联系人的对话框。

如需从应用主屏幕打开对话框，请使用以下代码处理相关互动事件：返回 renderActions，且 updateCard 导航包含 Card 对象。在以下示例中，聊天应用通过处理 CARD_CLICKED 互动事件并打开对话框，响应应用主屏幕卡片中的按钮点击：

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

如需关闭对话框，请处理以下互动事件：

CLOSE_DIALOG：关闭对话框并返回 Chat 应用的初始应用首页卡片。
CLOSE_DIALOG_AND_EXECUTE：关闭对话框并刷新应用首页卡片。

以下代码示例使用 CLOSE_DIALOG 关闭对话框并返回到应用首页卡片：

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

为了向用户收集信息，您还可以构建顺序对话框。如需了解如何构建顺序对话框，请参阅打开和响应对话框。

为 Google Chat 应用构建首页

前提条件

Node.js

Python

Java

Apps 脚本

为 Chat 应用配置应用主屏幕

构建应用首页卡片

Node.js

Python

Java

Apps 脚本

响应应用主屏幕互动

Node.js

Python

Java

Apps 脚本

打开对话框

相关主题