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

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

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

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

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

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

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

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

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

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

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

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

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

Ниже представлена ​​карточка, состоящая из трех различных типов ввода даты и времени:

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

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

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

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

{
  "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
      }
    ]
  }
}

Обработка события взаимодействия

Когда пользователь вводит данные в карточку или диалоговое окно, ваше приложение Chat получает событие взаимодействия приложения Chat CARD_CLICKED , которое содержит значения, введенные пользователем.

Ниже показана часть события взаимодействия 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 events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Чтобы получить первое или единственное значение, events.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker , который принимает только даты. dateInput events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch . 1000425600000

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

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

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

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

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

Где WIDGET_NAME — это name виджета, а USER_INPUT_VALUE — это то, что вводит пользователь. Например, для ввода текста, который собирает имя человека, имя виджета — contactName , а примерное значение — Kai O

Когда пользователь нажимает кнопку, ваше приложение Chat получает событие взаимодействия CARD_CLICKED . Чтобы получить значения, вы можете использовать объект event.common.parameters .

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

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Питон

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

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

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

Ответ на отправку формы

После получения данных из карточного сообщения или диалогового окна приложение Chat отвечает либо подтверждением получения, либо возвратом ошибки.

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

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

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

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

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

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

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