Ta strona została przetłumaczona przez Cloud Translation API.

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

Tester wersji dla deweloperów: dostępny w ramach Programu testów wersji dla deweloperów Google Workspace, który zapewnia wcześniejszy dostęp do niektórych funkcji.

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.

W Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Więcej informacji znajdziesz w artykule Więcej informacji o rozszerzaniu Google Chat.

Ilustracja 1.: Aplikacja Google Chat 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. Na przykład aplikacja Google Chat może pomóc użytkownikom zaktualizować stan zgłoszenia do zespołu pomocy bezpośrednio w pokoju czatu.

Wymagania wstępne

Node.js

Dodatek Google Workspace, który działa w Google Chat. Aby go utworzyć, wykonaj czynności opisane w krótkim przewodniku po HTTP.

Google Apps Script

Dodatek Google Workspace, który działa w Google Chat. Aby utworzyć taki skrypt, zapoznaj się z krótkim przewodnikiem po Apps Script.

Tworzenie formularzy za pomocą kart

Aby zbierać informacje, aplikacje Google Chat projektują formularze i ich pola, 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 na czacie zawierające co najmniej 1 kartę;
Dialogi, czyli karty otwierane w nowym oknie z wiadomości i stron głównych.

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

Elementy formularzy, które wymagają od użytkowników podania informacji. Opcjonalnie możesz dodać weryfikację do formularzy z elementami wejściowymi, aby zapewnić prawidłowe wprowadzanie i formatowanie informacji przez użytkowników. Aplikacje do czatu mogą używać tych widżetów wprowadzania danych:
- 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. 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żą.
Uwaga: aby dynamicznie sugerować elementy do wyboru w menu z wielokrotnie wybieranymi opcjami, użyj działania RenderActions z obiektem modifyCard.
- 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 godziny oraz pola wyboru:

Więcej przykładów interaktywnych widżetów, których możesz używać do zbierania informacji, znajdziesz w dokumentacji interfejsu Google Chat API Projektowanie interaktywnej karty lub dialogu.

Otrzymywanie danych z interaktywnych widżetów

Gdy użytkownik kliknie przycisk, działanie aplikacji Google Chat zostanie wywołane z informacjami o interakcji. W ładunku zdarzenia commonEventObject obiekt formInputs zawiera wszystkie wartości wprowadzone przez użytkownika.

Wartości możesz pobrać z obiektu commonEventObject.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.

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

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

Aby otrzymywać dane, aplikacja do obsługi czatu obsługuje obiekt zdarzenia, aby pobierać wartości wprowadzane przez użytkowników w widżetach. Poniższa tabela pokazuje, jak uzyskać wartość danego widżetu formularza. W tabeli dla każdego widżetu podano typ danych, który jest przez niego obsługiwany, miejsce przechowywania wartości w obiekcie zdarzenia oraz przykładową wartość.

Widżet pola formularza	Typ danych wejściowych	Wartość wejściowa z obiektu zdarzenia	Przykładowa wartość
`textInput`	`stringInputs`	`event.commonEventObject.formInputs.contactName.stringInputs.value[0]`	`Kai O`
`selectionInput`	`stringInputs`	Aby uzyskać pierwszą lub jedyną wartość, `event.commonEventObject.formInputs.contactType.stringInputs.value[0]`	`Personal`
`dateTimePicker`, który akceptuje tylko daty.	`dateInput`	`event.commonEventObject.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ł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:

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Gdzie WIDGET_NAME to name widżetu, a USER_INPUT_VALUE to dane wprowadzone przez użytkownika. Na przykład w przypadku danych wejściowych tekstowych służących do zbierania nazwisk osób nazwa widżetu to contactName, a przykładowa wartość to Kai O.

Gdy użytkownik kliknie przycisk, aplikacja Google Chat otrzyma obiekt zdarzenia, 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 do czatu wysyła wiadomość tekstową z potwierdzeniem, że otrzymała formularz przesłany z wiadomości na karcie.

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Google Apps Script

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Aby przetworzyć i zamknąć okno, zwracasz obiekt RenderActions, 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 dialogowego.

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 interfejs czatu nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta czatu powoduje nieoczekiwany wynik, na przykład wiadomość na karcie może się nie wyświetlić.

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ć. Aby dowiedzieć się, jak wyświetlać, debugować i naprawiać błędy, przeczytaj artykuł Rozwiązywanie problemów z błędami Google Chat.