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 poprzez tworzenie formularzy w interfejsach opartych na kartach.

Okno 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, 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 i ich aktualizowanie. Na przykład aplikacja Google Chat może pomóc użytkownikom zaktualizować stan zgłoszenia do zespołu pomocy bezpośrednio w pokoju Google Chat.

Wymagania wstępne

Node.js

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Python

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Java

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Google Apps Script

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację Google Chat w Apps Script, wykonaj samouczek.

Tworzenie formularzy za pomocą kart

Aby zbierać informacje, aplikacje Google Chat projektują formularze i ich pola wejściowe, a następnie umieszczają je na kartach. 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, która pojawia się na karcie Strona główna w wiadomościach bezpośrednich w aplikacji Google Chat.
  • Dialogi, czyli karty otwierane w nowym oknie z wiadomości i stron głównych.

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

  • widżety formularzy, które wymagają od użytkowników podania informacji; Opcjonalnie możesz dodać weryfikację do formularzy, aby mieć pewność, że użytkownicy będą prawidłowo wprowadzać i formatować informacje. Aplikacje do czatu mogą używać tych widżetów wprowadzania danych:

    • Tekst do wpisania (textInput) w celu wprowadzenia tekstu niesformatowanego lub sugerowanego.
    • Elementy wyboru (selectionInput) to elementy interfejsu, które można wybrać, takie jak pola wyboru, przyciski opcji i menu. Widgety danych wyboru mogą też wypełniać elementy z źródeł danych statycznych lub dynamicznych. 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 Czat może przetworzyć otrzymane informacje.

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

Przykład aplikacji czatu, która korzysta z tego formularza kontaktowego, znajdziesz w tym kodzie:

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 Google Chat otrzymują zdarzenie interakcji zależne od lokalizacji przycisku:

  • Jeśli przycisk znajduje się w wiadomości lub oknie dialogowym, aplikacje Google Chat otrzymują CARD_CLICKEDzdarzenie interakcji, 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 przez Ciebie 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"]
    }}}
  }}
}

  • Jeśli przycisk znajduje się na stronie głównej, aplikacje Google Chat otrzymują SUBMIT_FORMzdarzenie interakcji. Ładunek zdarzenia interakcji zawiera obiekt commonEventObject.formInputs z dowolnymi wartościami wprowadzonymi przez użytkownika.

    Wartości możesz pobrać z obiektu commonEventObject.formInputs.WIDGET_NAME, gdzie WIDGET_NAME to pole name określone przez Ciebie 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 SUBMIT_FORM, w którym użytkownik wprowadził wartości dla każdego widżetu:

    HTTP

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

    Google Apps Script 

    {
  "type": "SUBMIT_FORM",
  "commonEventObject": { "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 ze 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 oddzielne sekcje.
  • Pozwól użytkownikom wyświetlić i potwierdzić informacje z pierwotnej karty, aby mogli sprawdzić swoje odpowiedzi przed przesłaniem.
  • dynamicznie wypełnić 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 tym przykładzie aplikacja Google Chat wysyła wiadomość tekstową z potwierdzeniem, że otrzymała formularz przesłany z poziomu okna dialogowego lub wiadomości 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.
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

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

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

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

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 zwróci błąd, interfejs Google Chat wyświetli komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs czatu nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta czatu powoduje nieoczekiwany wynik, na przykład może nie wyświetlać się 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 ułatwiają ich rozwiązywanie. Aby dowiedzieć się, jak wyświetlać, debugować i naprawiać błędy, przeczytaj artykuł Rozwiązywanie problemów z błędami Google Chat.