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 pól formularza w interfejsach opartych na kartach.

Okno z różnymi różnymi widżetami.
Rysunek 1.: A przykład aplikację Google Chat, otwiera okno zbierania danych 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. Aby na przykład umożliwić użytkownikom dostosowywanie ustawień powiadomień albo skonfigurować i dodać aplikację Google Chat do spacje.
  • 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. Dla: na przykład aplikacja Google Chat może pomóc użytkownikom zgłoszenia do zespołu pomocy bezpośrednio w pokoju czatu.

Wymagania wstępne

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywną aplikację Google Chat, wykonaj jeden z tych samouczków w zależności od architektury aplikacji, której chcesz użyć:

Twórz formularze za pomocą kart

Aby zbierać informacje, formularze projektowe aplikacji do obsługi czatu i ich dane wejściowe i przekształcać je w karty. Aby wyświetlać karty użytkownikom: Aplikacje do obsługi czatu mogą korzystać z tych interfejsów Google Chat:

  • Wiadomości które zawierają co najmniej jedną kartę.
  • Strony główne, czyli kartę, która pojawia się na karcie Strona główna bezpośrednio wiadomości 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 widżetów wprowadzania danych, aby zapewnić prawidłowe wprowadzanie i formatowanie informacji przez użytkowników. Aplikacje do czatu mogą używać tych widżetów wprowadzania danych:

    • Dane wejściowe (textInput) w przypadku dowolnego tekstu.
    • Elementy wyboru (selectionInput) to elementy interfejsu, które można wybrać, takie jak pola wyboru, przyciski opcji i menu. Widżety wyboru można też wypełniają 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) aby wybrać 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 będzie mogła przetwarzać otrzymywane informacje.

Poniżej znajduje się karta zawierająca 3 różne typy daty dane wejściowe czasu:

Więcej przykładów interaktywnych widżetów, które można wykorzystać do zbierania danych Więcej informacji zawiera Zaprojektuj interaktywną kartę lub okno.

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.

Możesz pobrać wartości 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 widżetu (reprezentowany jako obiekt Inputs). W tym przykładzie karta zbiera informacje kontaktowe za pomocą pola tekstowego, selektora daty i godziny oraz pola wyboru:

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

Obsługa zdarzenia interakcji

Gdy użytkownik wprowadzi dane na karcie lub w dialogu, aplikacja Google Chat otrzyma zdarzenie interakcji CARD_CLICKED, które zawiera wartości wprowadzone przez użytkownika.

Poniżej widać fragment zdarzenia interakcji CARD_CLICKED, w którym wartości wprowadzone przez użytkownika 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 odbierać te dane, aplikacja Google Chat obsługuje zdarzenie interakcji, aby pobrać wartości wprowadzane przez użytkowników do widżetów. Poniżej Tabela pokazuje, jak uzyskać wartość dla danego widżetu z danymi wejściowymi do formularza. Dla każdego widżetu tabela pokazuje typ danych akceptowanych przez widżet i miejsce przechowywania wartości i przykładową wartość.

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

  • Aby ułatwić użytkownikom wypełnianie dłuższych formularzy, utwórz osobne sekcje.
  • Pozwól użytkownikom wyświetlić i potwierdzić informacje z pierwszej karty, aby mogli sprawdzić swoje odpowiedzi przed przesłaniem.
  • Dynamicznie wypełnij 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 wejściowe z początkowej karty, możesz utworzyć button widżet z actionParameters zawierające name widżetu i wartość wprowadzoną przez użytkownika, jak widać na ilustracji w tym przykładzie:

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

Gdzie WIDGET_NAME to nazwa name widżetu, a element USER_INPUT_VALUE to dane wejściowe użytkownika. Na przykład w przypadku tekstu dane wejściowe, które służą do zbierania imienia i nazwiska danej osoby, nazwa widżetu to contactName, a przykładowa wartość to Kai O.

Gdy użytkownik kliknie przycisk, aplikacja do obsługi czatu otrzyma zdarzenie interakcji CARD_CLICKED. Aby pobrać wartości, możesz użyć obiektu event.common.parameters.

Poniżej znajduje się przykład przekazywania parametrów zawierających nazwę użytkownika dane wejściowe funkcji, która otwiera następną kartę:

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

Google Apps Script 

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

Odpowiadanie na przesłany formularz

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

Google Apps Script 

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

Aby przetworzyć i zamknąć okno, musisz zwrócić ActionResponse określający, czy chcesz wysłać wiadomość potwierdzającą, aktualizować oryginalną wiadomość lub kartę albo po prostu zamknij okno. Instrukcje znajdziesz w artykule Zamykanie okna dialogowego.

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub card zwraca błąd, Interfejs czatu 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 nie wyświetlać się w interfejsie Google Chat, opisowe komunikaty o błędach i dane dziennika, które pomogą Ci w naprawianiu błędów gdy logowanie błędów aplikacji Google Chat jest włączone. Aby uzyskać pomoc w wyświetlaniu, debugowania i naprawiania błędów, zapoznaj się z artykułem Rozwiązywanie problemów z błędami w Google Chat