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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# 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
        }
      ]
    }
  }
]

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

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

  Apps Script

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

  Apps Script

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

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

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

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

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

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

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

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

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

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

Ответить на отправленную форму

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

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

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

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
    }}
  }}

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

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

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

Связанные темы

• Ознакомьтесь с примером приложения «Менеджер контактов» — это чат-приложение, которое предлагает пользователям заполнить контактную форму из сообщений в виде карточек и диалоговых окон.
• Открыть интерактивные диалоги