收集和处理 Google Chat 用户的信息

本指南介绍了 Google Chat 应用如何通过在基于卡片的界面中构建表单输入项来收集和处理用户信息。

一个包含各种不同 widget 的对话框。
图 1：Chat 应用示例，用于打开对话框以收集联系信息。

Chat 应用会向用户请求信息，以便在 Chat 中或之外执行操作，包括通过以下方式：

  • 配置设置。例如，允许用户自定义通知设置，或配置 Chat 应用并将其添加到一个或多个聊天室。
  • 在其他 Google Workspace 应用中创建或更新信息。例如，允许用户创建 Google 日历活动。
  • 允许用户访问和更新其他应用或 Web 服务中的资源。例如，Chat 应用可以帮助用户直接在 Chat 聊天室中更新支持服务工单的状态。

前提条件

Node.js

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

Python

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

Java

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

Apps 脚本

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

使用卡片构建表单

为了收集信息，Chat 应用会设计表单及其输入内容，并将其构建为卡片。如需向用户显示卡片，Chat 应用可以使用以下 Chat 界面：

  • 包含一个或多个卡片的消息。
  • 首页：一个卡片，显示在与 Chat 应用的私信首页标签页中。
  • 对话框：即从消息和首页在新窗口中打开的卡片。

聊天应用可以使用以下 widget 来构建卡片：

  • 用于请求用户信息的表单输入微件。（可选）您可以添加验证以形成输入 widget，以确保用户正确输入信息并设置格式。聊天应用可以使用以下表单输入 widget：

    • 文本输入 (textInput)，适用于自由格式文本或建议文本。
    • 选择输入 (selectionInput) 是可选择的界面元素，例如复选框、单选按钮和下拉菜单。选择输入 widget 还可以从静态或动态数据源填充项。例如，用户可以从他们所属的 Chat 聊天室列表中进行选择。
    • 日期时间选择器 (dateTimePicker)，用于日期和时间条目。

  • 一个按钮 widget，以便用户提交在卡片中输入的值。用户点击该按钮后，Chat 应用便可以处理收到的信息。

在以下示例中，卡片使用文本输入框、日期时间选择器和选择输入微件收集联系信息：

Node.js

node/contact-form-app/index.js
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py
# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": False
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": False
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps 脚本

apps-script/contact-form-app/contactForm.gs
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

如需查看更多可用于收集信息的交互式 widget 示例，请参阅设计交互式卡片或对话框。

接收来自互动 widget 的数据

每当用户点击按钮时，聊天应用都会收到包含交互相关信息的 CARD_CLICKED 互动事件。CARD_CLICKED 互动事件的载荷包含一个 common.formInputs 对象，其中包含用户输入的任何值。

您可以从对象 common.formInputs.WIDGET_NAME 检索值，其中 WIDGET_NAME 是您为该 widget 指定的 name 字段。这些值会以 widget 的特定数据类型（表示为 Inputs 对象）的形式返回。

以下是 CARD_CLICKED 互动事件的一部分，其中用户为每个 widget 输入了值：

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps 脚本

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

如需接收数据，您的 Chat 应用需要处理互动事件，以获取用户输入到 widget 中的值。下表展示了如何获取给定表单输入 widget 的值。对于每个 widget，该表会显示 widget 接受的数据类型、值在互动事件中的存储位置，以及示例值。

表单输入微件 输入数据类型 输入来自互动事件的值 示例值
textInput stringInputs event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs 如需获取第一个或唯一值，请使用 event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker，只接受日期。 dateInput event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch。 1000425600000

将数据转移到其他卡

用户提交卡片信息后，您可能需要返回其他卡片才能执行以下任一操作：

  • 通过创建不同的部分，帮助用户填写较长的表单。
  • 让用户预览并确认初始卡片中的信息，以便在提交之前检查答案。
  • 动态填充表单的其余部分。例如，为了提示用户创建预约，Chat 应用可以显示一个初始卡片来请求预约原因，然后填充另一张卡片，根据预约类型提供空闲时间。

如需从初始卡片传输数据输入，您可以使用包含微件 name 和用户输入的值的 actionParameters 构建 button 微件，如以下示例所示：

Node.js

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps 脚本

apps-script/contact-form-app/main.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

当用户点击该按钮时，您的 Chat 应用会收到 CARD_CLICKED 互动事件，您可以从中接收数据。

回复表单提交

从卡片消息或对话框收到数据后，Chat 应用会通过确认收到或返回错误来响应。

在以下示例中，Chat 应用发送一条短信，确认已成功收到通过对话框或卡片消息提交的表单。

Node.js

node/contact-form-app/index.js
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

Python

python/contact-form-app/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
if contact_name == "":
  error_message = "Don't forget to name your new contact!"
  if "SUBMIT_DIALOG" == event.get('dialogEventType'):
    return { 'actionResponse': {
      'type': "DIALOG",
      'dialogAction': { 'actionStatus': {
        'statusCode': "INVALID_ARGUMENT",
        'userFacingMessage': error_message
      }}
    }}
  else:
    return {
      'privateMessageViewer': event.get('user'),
      'text': error_message
    }

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (contactName.isEmpty()) {
  String errorMessage = "Don't forget to name your new contact!";
  if (event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
    return new Message().setActionResponse(new ActionResponse()
      .setType("DIALOG")
      .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
        .setStatusCode("INVALID_ARGUMENT")
        .setUserFacingMessage(errorMessage))));
  } else {
    return new Message()
      .setPrivateMessageViewer(new User().setName(event.at("/user/name").asText()))
      .setText(errorMessage);
  }
}

Apps 脚本

apps-script/contact-form-app/main.gs
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

如需处理和关闭对话框，您需要返回一个 ActionResponse 对象，用于指定您是要发送确认消息、更新原始消息或卡片，还是只关闭对话框。如需了解相关步骤，请参阅关闭对话框。

问题排查

当 Google Chat 应用或卡片返回错误时，Chat 界面会显示“出了点问题”消息。或“无法处理您的请求”。有时，Chat 界面不显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。

虽然 Chat 界面中可能不会显示错误消息，但当 Chat 应用的错误日志记录功能处于开启状态时，描述性错误消息和日志数据可帮助您修正错误。如需有关查看、调试和修复错误的帮助，请参阅排查和修复 Google Chat 错误。