Zbieranie i przetwarzanie informacji od użytkowników Google Chat

W tym przewodniku opisano, jak aplikacje Google Chat mogą zbierać i przetwarzać informacje od użytkowników dzięki tworzeniu formularzy w interfejsach opartych na kartach.

Dialog z różnymi widżetami.
Ilustracja 1. Przykładowa aplikacja Google Chat, która otwiera okno dialogowe do zbierania informacji kontaktowych.

Aplikacje do obsługi czatu proszą użytkowników o informacje, które umożliwiają wykonywanie działań w Google Chat lub poza nią. Oto niektóre z nich:

  • Skonfiguruj ustawienia. Na przykład, aby umożliwić użytkownikom dostosowywanie ustawień powiadomień lub skonfigurowanie i dodanie aplikacji Google Chat do jednego lub większej liczby pokoi.
  • tworzenia i aktualizowania informacji w innych aplikacjach Google Workspace; Możesz na przykład zezwolić użytkownikom na tworzenie wydarzeń w Kalendarzu Google.
  • Zezwalanie użytkownikom na dostęp do zasobów w innych aplikacjach lub usługach internetowych oraz ich aktualizowanie. Aplikacja Google Chat może na przykład pomóc użytkownikom w aktualizacji stanu zgłoszenia bezpośrednio w pokoju czatu.

Wymagania wstępne

Node.js

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację do obsługi czatu przy użyciu usługi HTTP, wykonaj to krótkie wprowadzenie.

Python

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywną aplikację Google Chat przy użyciu usługi HTTP, wykonaj to krótkie wprowadzenie.

Java

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat przy użyciu usługi HTTP, wykonaj to krótkie wprowadzenie.

Google Apps Script

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację do obsługi czatu w Apps Script, zapoznaj się z tym krótkim wprowadzeniem.

Tworzenie formularzy za pomocą kart

Aplikacje do obsługi czatu projektują formularze i dane wejściowe i wkładają je w karty. Aby wyświetlać karty użytkownikom, aplikacje na czacie mogą korzystać z tych interfejsów czatu:

  • Wiadomości zawierające co najmniej 1 kartę.
  • Strony główne: karta wyświetlana na karcie Strona główna w czatach w aplikacji Google Chat.
  • Okna – karty, które z wiadomości i stron głównych otwierają się w nowym oknie.

Aplikacje do obsługi czatu mogą tworzyć karty za pomocą tych widżetów:

  • Widżety do wprowadzania danych do formularzy, które proszą użytkowników o podanie informacji. Opcjonalnie możesz dodać weryfikację do formularzy, aby zapewnić prawidłowe wprowadzanie i formatowanie informacji przez użytkowników. Aplikacje do obsługi czatu mogą korzystać z tych widżetów do wprowadzania danych do formularzy:

    • Tekst do wpisania (textInput) w postaci tekstu niesformatowanego lub sugerowanego.
    • Elementy wyboru (selectionInput) to elementy interfejsu, które można wybrać, takie jak pola wyboru, przyciski opcji i menu. Widżety wyboru mogą też wypełniać elementy ze statycznych lub dynamicznych źródeł danych. Użytkownicy mogą na przykład wybrać pokój czatu z listy pokoi, do których należą.
    • Selektory daty i godziny (dateTimePicker) do wpisów z datą i godziną.

  • Przycisk, dzięki któremu użytkownicy mogą przesyłać wartości wprowadzone na karcie. Gdy użytkownik kliknie przycisk, aplikacja Google Chat może przetworzyć otrzymane informacje.

W tym przykładzie karta zbiera informacje kontaktowe za pomocą pola tekstowego, selektora daty i godziny oraz pola wyboru:

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

Google Apps Script

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

Więcej przykładów interaktywnych widżetów, które możesz wykorzystać do zbierania informacji, znajdziesz w artykule Projektowanie interaktywnej karty lub dialogu.

Otrzymywanie danych z interaktywnych widżetów

Gdy użytkownicy klikają przycisk, aplikacje do czatu otrzymują zdarzenie interakcji CARD_CLICKED, które zawiera informacje o tej interakcji. Ładunek zdarzeń interakcji CARD_CLICKED zawiera obiekt common.formInputs z dowolnymi wartościami wprowadzonymi przez użytkownika.

Wartości możesz pobrać z obiektu common.formInputs.WIDGET_NAME, gdzie WIDGET_NAME to pole name określone dla widżetu. Wartości są zwracane jako określony typ danych dla widżetu (przedstawiany jako obiekt Inputs).

Poniżej widać fragment zdarzenia interakcji CARD_CLICKED, w którym użytkownik wprowadził wartości dla każdego widżetu:

HTTP

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

Google Apps Script 

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

Aby otrzymywać dane, aplikacja Google Chat obsługuje zdarzenie interakcji, aby pobierać wartości wprowadzane przez użytkowników w widżetach. Poniższa tabela pokazuje, jak uzyskać wartość danego widżetu formularza. W przypadku każdego widżetu tabela zawiera typ danych, który akceptuje, miejsce przechowywania wartości w zdarzeniu interakcji oraz przykładową wartość.

Widżet pola formularza Typ danych wejściowych Wartość wejściowa zdarzenia interakcji Przykładowa wartość
textInput stringInputs event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Aby uzyskać pierwszą lub jedyną wartość, event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker, który akceptuje tylko daty. dateInput event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

Przenoszenie danych na inną kartę

Gdy użytkownik prześle informacje z karty, może być konieczne zwrócenie dodatkowych kart, aby wykonać jedną z tych czynności:

  • Ułatwiaj użytkownikom wypełnianie dłuższych formularzy, tworząc odrębne sekcje.
  • Pozwól użytkownikom wyświetlić i potwierdzić informacje z pierwotnej karty, aby mogli sprawdzić swoje odpowiedzi przed przesłaniem.
  • dynamicznie wypełniać pozostałe części formularza; Aby na przykład zachęcić użytkowników do utworzenia spotkania, aplikacja Chat może wyświetlić kartę z prośbą o podanie powodu spotkania, a następnie wypełnić kolejną kartę z dostępnymi godzinami na podstawie typu spotkania.

Aby przenieść dane z pierwotnej karty, możesz utworzyć widżet button z actionParameters, który zawiera name widżetu i wartość wprowadzoną przez użytkownika, jak pokazano w tym przykładzie:

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

Google Apps Script

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

Gdy użytkownik kliknie przycisk, aplikacja Google Chat otrzyma zdarzenie interakcji CARD_CLICKED, z którego możesz otrzymać dane.

Odpowiedź na przesłanie formularza

Po otrzymaniu danych z wiadomości na karcie lub z dialogu aplikacja Google Chat potwierdza otrzymanie danych lub zwraca błąd.

W poniższym przykładzie aplikacja Google Chat wysyła SMS-a, aby potwierdzić, że otrzymała formularz przesłany z okna dialogowego lub komunikatu na karcie.

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

Google Apps Script

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

Aby przetworzyć i zamknąć okno, zwracasz obiekt ActionResponse, który określa, czy chcesz wysłać wiadomość z potwierdzeniem, zaktualizować pierwotną wiadomość lub kartę, czy po prostu zamknąć okno. Instrukcje znajdziesz w artykule Zamykanie okna.

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub karta zwraca błąd, interfejs Google Chat wyświetla komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami w UI Google Chat nie wyświetla się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład wiadomość na karcie.

Komunikat o błędzie może się nie wyświetlać w interfejsie czatu, ale gdy włączone jest rejestrowanie błędów w przypadku aplikacji czatu, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci je naprawić. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami w Google Chat.