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

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

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

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

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

Предпосылки

Node.js

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

Питон

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

Ява

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

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

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

Создавайте формы с использованием карточек

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

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

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

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

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

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

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

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

Node.js

узел/контакт-форма-приложение/index.js

Посмотреть на GitHub

/**
 * 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

Посмотреть на GitHub

# 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

Посмотреть на GitHub

// 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-script/contact-form-app/contactForm.gs

Посмотреть на GitHub

/**
 * 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
        }
      ]
    }
  }
];

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

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

Дополнительные примеры см. в разделе Примеры приложений Google Chat .

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

• Если кнопка находится в сообщении или диалоге, приложения Chat получают событие взаимодействия 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"]
      }}}
    }}
  }
  

• Если кнопка находится на домашней странице , приложения чата получают событие взаимодействия SUBMIT_FORM . Полезная нагрузка события взаимодействия содержит объект commonEventObject.formInputs со всеми значениями, которые вводит пользователь.

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

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

  HTTP

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

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

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

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

Важно: если ваше приложение чата создано с помощью Apps Script, необходимо добавить [""] после имени виджета, например, formInputs.contactName[""].stringInputs.value[0] .

Виджет ввода формы	Тип входных данных	Входное значение из события взаимодействия	Пример значения
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 может отображать начальную карточку, которая запрашивает причину встречи, а затем заполнять другую карточку, которая предоставляет доступное время на основе типа встречи.

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

Node.js

узел/контакт-форма-приложение/index.js

Посмотреть на GitHub

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

Посмотреть на GitHub

'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

Посмотреть на GitHub

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

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

приложения-скрипт/контакт-форма-app/main.gs

Посмотреть на GitHub

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

Посмотреть на GitHub

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.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Питон

python/contact-form-app/main.py

Посмотреть на GitHub

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.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': error_message
    }}
  }}

Ява

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

Посмотреть на GitHub

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.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && 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))));
}

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

приложения-скрипт/контакт-форма-app/main.gs

Посмотреть на GitHub

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.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

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

Устранение неполадок

Когда приложение или карта Google Chat возвращает ошибку, интерфейс Chat отображает сообщение «Что-то пошло не так» или «Не удалось обработать ваш запрос». Иногда интерфейс Chat не отображает никаких сообщений об ошибках, но приложение или карта Chat выдает неожиданный результат; например, сообщение карты может не отображаться.

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

Похожие темы

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