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.

Okno z różnymi 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 wymagają od użytkowników informacji, aby wykonywać działania w Google Chat lub poza nim, w tym w następujący sposób:

  • 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.
  • tworzyć i aktualizować informacje w innych aplikacjach Google Workspace. Na przykład możesz 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 można korzystać z funkcji interaktywnych. Aby utworzyć interaktywną aplikację Google Chat 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ę do obsługi czatu 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 Google Chat mogą używać tych interfejsów Google Chat:

  • Wiadomości zawierające co najmniej jedną kartę.
  • Strony główne – karta, która pojawia się na karcie Strona główna w wiadomościach bezpośrednich 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 widżetów danych wejściowych, aby mieć pewność, że użytkownicy poprawnie wprowadzają i formatują informacje. 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.
    • Dane wejściowe (selectionInput) to elementy interfejsu, które można wybrać, takie jak pola wyboru, opcje 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ą.

  • Widżet przycisku, za pomocą którego użytkownicy mogą przesyłać wartości wpisane na karcie. Gdy użytkownik kliknie przycisk, aplikacja Czat może przetworzyć otrzymane informacje.

W tym przykładzie karta zbiera informacje kontaktowe za pomocą pola do wprowadzania tekstu, selektora daty i godziny oraz widżetu do wprowadzania danych:

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.

Odbieranie 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 wpisywanymi przez użytkownika.

Możesz pobrać wartości 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 wpisał wartości 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. W tabeli poniżej pokazujemy, jak uzyskać wartość dla danego widżetu z danymi wejściowymi do formularza. W przypadku każdego widżetu tabela zawiera typy danych akceptowane przez widżet, miejsce, w którym wartość jest przechowywana w zdarzeniu interakcji, oraz przykładową wartość.

Widżet wprowadzania danych do 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 na podgląd informacji z pierwotnej karty i potwierdzenie ich, aby mogli sprawdzić swoje odpowiedzi przed przesłaniem.
  • Dynamicznie wypełnij pozostałe części formularza. Aby na przykład poprosić użytkowników o umówienie się na spotkanie, aplikacja Google Chat może wyświetlić początkową kartę z prośbą o powód spotkania, a następnie wypełnia kolejną kartę z dostępnymi terminami na podstawie typu spotkania.

Aby przenieść dane wejściowe z pierwszej karty, możesz utworzyć widżet button z actionParameters, który zawiera wartość name widżetu oraz wartość wprowadzoną przez użytkownika, jak 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 ten przycisk, aplikacja do obsługi czatu otrzyma zdarzenie interakcji CARD_CLICKED, z którego możesz otrzymywać dane.

Odpowiedź na przesłanie formularza

Po otrzymaniu danych z komunikatu na karcie lub okna dialogowego aplikacja Google Chat odpowiada, potwierdzając potwierdzenie lub zwracając komunikat o błędzie.

W tym przykładzie aplikacja Google Chat wysyła wiadomość tekstową z potwierdzeniem, że otrzymała formularz przesłany z poziomu okna dialogowego lub karty.

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 lub karta w Google Chat zwróci błąd, w interfejsie Google Chat pojawi się komunikat „Coś poszło nie tak”. lub „Nie można przetworzyć żądania”. 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.