Собирайте и обрабатывайте информацию от пользователей Google Chat.

В этом руководстве описывается, как приложения Google Chat могут собирать и обрабатывать информацию от пользователей, создавая поля ввода форм в интерфейсах на основе карточек.

Диалог с множеством различных виджетов.
Рис. 1. Пример приложения чата , открывающего диалоговое окно для сбора контактной информации.

Приложения чата запрашивают у пользователей информацию для выполнения действий в чате или за его пределами, в том числе следующими способами:

  • Настройте параметры. Например, чтобы позволить пользователям настраивать параметры уведомлений или настраивать и добавлять приложение Chat в одно или несколько пространств.
  • Создавайте или обновляйте информацию в других приложениях Google Workspace. Например, разрешите пользователям создавать события Календаря Google.
  • Разрешите пользователям получать доступ и обновлять ресурсы в других приложениях или веб-службах. Например, приложение чата может помочь пользователям обновить статус заявки в службу поддержки непосредственно из пространства чата.

Предварительные условия

Node.js

Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата с использованием службы HTTP, выполните это краткое руководство .

Питон

Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата с использованием службы HTTP, выполните это краткое руководство .

Ява

Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата с использованием службы HTTP, выполните это краткое руководство .

Скрипт приложений

Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата с помощью Apps Script, выполните это краткое руководство .

Создавайте формы с помощью карточек

Для сбора информации приложения чата разрабатывают формы и входные данные, а затем встраивают их в карточки. Для отображения карточек пользователям приложения чата могут использовать следующие интерфейсы чата:

  • Сообщения , содержащие одну или несколько карточек.
  • Домашние страницы — карточка, которая появляется на вкладке «Главная» в личных сообщениях в приложении Chat.
  • Диалоги — карточки, открывающиеся в новом окне из сообщений и домашних страниц.

Приложения чата могут создавать карточки с помощью следующих виджетов:

  • Формируйте виджеты ввода, которые запрашивают информацию у пользователей. При желании вы можете добавить проверку формы виджетов ввода, чтобы гарантировать, что пользователи правильно вводят и форматируют информацию. Приложения чата могут использовать следующие виджеты ввода форм:

    • Текстовые входы ( textInput ) для произвольного или предлагаемого текста.
    • Входные данные выбора ( selectionInput ) — это выбираемые элементы пользовательского интерфейса, такие как флажки, переключатели и раскрывающиеся меню. Виджеты ввода выбора также могут заполнять элементы из статических или динамических источников данных. Например, пользователи могут выбирать из списка чат-групп, участниками которых они являются.
    • Средства выбора даты и времени ( dateTimePicker ) для записей даты и времени.

  • Виджет кнопки , позволяющий пользователям отправлять значения, которые они ввели в карточку. После того, как пользователь нажмет кнопку, приложение Chat сможет обработать полученную информацию .

В следующем примере карточка собирает контактную информацию с помощью текстового ввода, средства выбора даты и времени и ввода выбора:

Пример приложения чата, использующего эту контактную форму, см. в следующем коде:

Node.js

узел/контактная форма-приложение/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/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/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)))));

Скрипт приложений

приложения-скрипт/контакт-форма-приложение/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
        }
      ]
    }
  }
];

Дополнительные примеры интерактивных виджетов, которые можно использовать для сбора информации, см. в разделе «Разработка интерактивной карточки или диалога» .

Получайте данные от интерактивных виджетов

Каждый раз, когда пользователи нажимают кнопку, приложения чата получают событие взаимодействия CARD_CLICKED , содержащее информацию о взаимодействии. Полезная нагрузка событий взаимодействия CARD_CLICKED содержит объект common.formInputs с любыми значениями, которые вводит пользователь.

Вы можете получить значения из объекта common.formInputs. WIDGET_NAME , где WIDGET_NAME — это поле name , указанное вами для виджета. Значения возвращаются как определенный тип данных для виджета (представленный как объект Inputs ).

Ниже показана часть события взаимодействия CARD_CLICKED , где пользователь ввел значения для каждого виджета:

HTTP 

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

Скрипт приложений 

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

Чтобы получить данные, ваше приложение чата обрабатывает событие взаимодействия, чтобы получить значения, которые пользователи вводят в виджеты. В следующей таблице показано, как получить значение для данного виджета ввода формы. Для каждого виджета в таблице показан тип данных, который принимает виджет, где значение сохраняется в событии взаимодействия, а также пример значения.

Виджет ввода формы Тип входных данных Входное значение из события взаимодействия Пример значения
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

Перенос данных на другую карту

После того как пользователь отправит информацию с карты, вам может потребоваться вернуть дополнительные карты, чтобы выполнить одно из следующих действий:

  • Помогите пользователям заполнять более длинные формы, создавая отдельные разделы.
  • Разрешите пользователям просматривать и подтверждать информацию из исходной карточки, чтобы они могли просмотреть свои ответы перед отправкой.
  • Динамически заполняйте остальные части формы. Например, чтобы предложить пользователям создать встречу, приложение чата может отображать начальную карточку, в которой запрашивается причина встречи, а затем заполняется другая карточка, указывающая доступное время в зависимости от типа встречи.

Чтобы перенести ввод данных из исходной карты, вы можете создать виджет button с actionParameters , которые содержат name виджета и значение, введенное пользователем, как показано в следующем примере:

Node.js

узел/контакт-форма-приложение/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Питон

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/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))))))))));

Скрипт приложений

приложения-скрипт/контакт-форма-приложение/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 отвечает либо подтверждением получения, либо возвратом ошибки.

В следующем примере приложение чата отправляет текстовое сообщение, чтобы подтвердить, что оно успешно получило форму, отправленную из диалогового окна или сообщения карточки.

Node.js

узел/контакт-форма-приложение/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/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/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);
  }
}

Скрипт приложений

приложения-скрипт/контакт-форма-приложение/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 отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.

Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .