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

Z tego przewodnika dowiesz się, jak aplikacje Google Chat mogą zbierać i przetwarzać informacje od użytkowników, tworząc dane wejściowe formularza w interfejsach opartych na kartach.

Aplikacje do 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. Może to być na przykład umożliwienie użytkownikom dostosowywania ustawień powiadomień lub konfigurowania i dodawania aplikacji Chat do co najmniej jednego pokoju.
• tworzyć lub aktualizować informacje w innych aplikacjach Google Workspace; Na przykład zezwól użytkownikom na tworzenie wydarzeń w Kalendarzu Google.
• umożliwiać użytkownikom dostęp do zasobów w innych aplikacjach lub usługach internetowych i ich aktualizowanie; Na przykład aplikacja do obsługi czatu może pomagać użytkownikom w aktualizowaniu stanu zgłoszenia bezpośrednio z poziomu pokoju w Google Chat.

Wymagania wstępne

Tworzenie formularzy za pomocą kart

Aby zbierać informacje, aplikacje w Google Chat projektują formularze i ich pola wejściowe oraz tworzą z nich karty. Aby wyświetlać karty użytkownikom, aplikacje do obsługi czatu mogą korzystać z tych interfejsów Google Chat:

• wiadomości na czacie zawierające co najmniej 1 kartę;
• Okna dialogowe, czyli karty, które otwierają się 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 do wprowadzania danych w formularzu, które proszą użytkowników o informacje. Opcjonalnie możesz dodać weryfikację do widżetów wprowadzania danych w formularzu, aby mieć pewność, że użytkownicy wprowadzają i formatują informacje prawidłowo. Aplikacje do obsługi czatu mogą używać tych widżetów do wprowadzania danych:

  • Pola tekstowe (textInput) do wpisywania tekstu w dowolnej formie lub sugerowanego tekstu.

  • Opcje wyboru (selectionInput) to elementy interfejsu, które można wybrać, np. pola wyboru, przyciski opcji i menu. Widżety wprowadzania wyboru mogą też wypełniać i sugerować elementy z danych Google Workspace (np. z przestrzeni w Google Chat) lub dynamicznego źródła danych. Szczegółowe informacje znajdziesz w sekcji Dodawanie menu wielokrotnego wyboru.

  • Selektory daty i godziny (dateTimePicker) do wprowadzania daty i godziny.

• Przycisk, aby użytkownicy mogli przesyłać wartości wpisane na karcie. Gdy użytkownik kliknie przycisk, aplikacja Google Chat może przetworzyć otrzymane informacje.

W tym przykładzie karta zbiera dane 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 artykule Projektowanie interaktywnej karty lub okna w dokumentacji interfejsu Google Chat API.

Dodawanie menu wielokrotnego wyboru

Aby dostosować elementy wyboru lub umożliwić użytkownikom wybieranie elementów z dynamicznego źródła danych, aplikacje na czacie mogą używać menu wielokrotnego wyboru, które są rodzajem widżetu SelectionInput. Na przykład poniższa karta zawiera menu wielokrotnego wyboru, w którym użytkownicy mogą dynamicznie wybierać elementy z listy kontaktów:

Elementy menu wielokrotnego wyboru możesz wypełniać danymi z tych źródeł:

• dane Google Workspace, które obejmują użytkowników lub pokoje czatu, których użytkownik jest członkiem; Menu zawiera tylko elementy z tej samej organizacji Google Workspace.
• zewnętrzne źródła danych, np. relacyjna baza danych; Możesz na przykład użyć menu wielokrotnego wyboru, aby pomóc użytkownikowi wybrać z listy potencjalnych klientów z systemu zarządzania relacjami z klientami (CRM).

Wypełnianie elementów z źródła danych Google Workspace

Aby używać źródeł danych Google Workspace, w widżecie SelectionInput określ pole platformDataSource. W przeciwieństwie do innych typów danych wejściowych wyboru możesz pominąć obiekty SelectionItem, ponieważ te elementy wyboru są dynamicznie pobierane z Google Workspace.

Poniższy kod pokazuje menu wielokrotnego wyboru użytkowników Google Workspace. Aby wypełnić listę użytkowników, dane wejściowe wyboru ustawiają wartość commonDataSource na USER:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Poniższy kod pokazuje menu wielokrotnego wyboru przestrzeni na czacie. Aby wypełnić miejsca, w polu wyboru należy określić pole hostAppDataSource. W menu wielokrotnego wyboru ustawia się też wartość defaultToCurrentSpace na true, co sprawia, że bieżący pokój jest domyślnie wybierany w menu:

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Wypełnianie elementów na podstawie zewnętrznego źródła danych

Menu wielokrotnego wyboru mogą też zawierać elementy pochodzące ze źródła danych zewnętrznego lub firmy zewnętrznej. Aby użyć zewnętrznego źródła danych, w widżecie SelectionInput musisz określić pole externalDataSource, które zawiera funkcję wysyłającą zapytania do źródła danych i zwracającą z niego elementy.

Aby zmniejszyć liczbę żądań wysyłanych do zewnętrznego źródła danych, możesz uwzględnić sugerowane elementy, które pojawiają się w menu wielokrotnego wyboru, zanim użytkownicy zaczną wpisywać tekst w menu. Możesz na przykład wypełnić listę ostatnio wyszukiwanych kontaktów użytkownika. Aby wypełnić sugerowane produkty z zewnętrznego źródła danych, określ statyczne obiekty SelectionItem.

Poniższy kod przedstawia menu wielokrotnego wyboru, które wysyła zapytania do zewnętrznego źródła danych i wypełnia je elementami:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

Zastąp FUNCTION adresem URL HTTP lub nazwą funkcji Apps Script, która wysyła zapytanie do zewnętrznej bazy danych. Pełny przykład pokazujący, jak zwracać sugerowane elementy, znajdziesz w sekcji Sugerowanie elementów wielokrotnego wyboru.

Otrzymywanie danych z interaktywnych widżetów

Gdy użytkownicy klikną przycisk, wywoływane jest działanie aplikacji Google Chat, które zawiera informacje o interakcji. W sekcji commonEventObject ładunku zdarzenia obiekt formInputs zawiera wszystkie wartości wpisane 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 widżetu.

Poniżej przedstawiamy fragment obiektu zdarzenia, w którym użytkownik wpisał wartości w poszczególnych widżetach:

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

Aby otrzymać dane, aplikacja w Google Chat przetwarza obiekt zdarzenia, aby uzyskać wartości wprowadzane przez użytkowników w widżetach. W tabeli poniżej pokazujemy, jak uzyskać wartość danego widżetu wejściowego formularza. W przypadku każdego widżetu tabela zawiera typ danych, które akceptuje widżet, miejsce przechowywania wartości w obiekcie zdarzenia oraz przykładową wartość.

Po otrzymaniu danych aplikacja do obsługi czatu może wykonać dowolną z tych czynności:

• W przypadku kart zawierających menu wielokrotnego wyboru wypełniaj lub sugeruj elementy na podstawie tego, co użytkownik wpisuje w menu.
• Przenieś dane na inną kartę, aby użytkownik mógł sprawdzić swoje informacje lub przejść do następnej sekcji formularza.
• Odpowiedz użytkownikowi, aby potwierdzić, że użytkownik prawidłowo wypełnił formularz.

Sugerowanie elementów wielokrotnego wyboru

Jeśli karta zawiera menu wielokrotnego wyboru, które wypełnia elementy z zewnętrznego źródła danych, aplikacja Chat może zwracać sugerowane elementy na podstawie tego, co użytkownicy wpisują w menu. Jeśli na przykład użytkownik zacznie wpisywać Atl w menu, które zawiera miasta w Stanach Zjednoczonych, Twoja aplikacja w Google Chat może automatycznie zasugerować Atlanta, zanim użytkownik skończy wpisywać. Aplikacja Chat może sugerować maksymalnie 100 produktów.

Aby sugerować i dynamicznie wypełniać elementy w menu wielokrotnego wyboru, widżet SelectionInput na karcie musi określać funkcję, która wysyła zapytania do zewnętrznego źródła danych. Aby zwrócić sugerowane produkty, funkcja musi wykonać te czynności:

1. Obsługuj obiekt zdarzenia, który aplikacja do obsługi czatu otrzymuje, gdy użytkownicy wpisują tekst w menu.
2. Z obiektu zdarzenia pobierz wartość wpisaną przez użytkownika, która jest reprezentowana w polu event.commonEventObject.parameters["autocomplete_widget_query"].
3. Wysyłaj do źródła danych zapytania z wartością wprowadzoną przez użytkownika, aby uzyskać co najmniej jednąSelectionItems do zaproponowania użytkownikowi.
4. Zwróć sugerowane produkty, zwracając działanie RenderActions z modifyCard obiektem.

Poniższy przykładowy kod pokazuje, jak aplikacja do obsługi czatu dynamicznie sugeruje elementy w menu wielokrotnego wyboru na karcie. Gdy użytkownik wpisuje tekst w menu, funkcja lub punkt końcowy podany w polu externalDataSource widżetu wysyła zapytanie do zewnętrznego źródła danych i sugeruje elementy, które użytkownik może wybrać.

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.selectionInput = function selectionInput(req, res) {
  if (req.method === 'GET' || !req.body.chat) {
    return res.send('Hello! This function is meant to be used ' +
        'in a Google Chat Space.');
  }
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Przenoszenie danych na inną kartę

Gdy użytkownik prześle informacje z karty, możesz potrzebować dodatkowych kart, aby wykonać jedną z tych czynności:

• Ułatw użytkownikom wypełnianie dłuższych formularzy, tworząc w nich osobne sekcje.
• Umożliwiaj użytkownikom wyświetlanie podglądu informacji z początkowej karty i ich potwierdzanie, aby mogli sprawdzić odpowiedzi przed przesłaniem.
• dynamicznie wypełniać pozostałe części formularza. Na przykład, aby zachęcić użytkowników do utworzenia spotkania, aplikacja do czatu może wyświetlić początkową kartę z prośbą o podanie powodu spotkania, a następnie wypełnić inną kartę, która zawiera dostępne terminy na podstawie typu spotkania.

Aby przenieść dane wejściowe z pierwszej karty, możesz utworzyć widżet button z elementem actionParameters zawierającym name widżetu i wartość wprowadzoną przez użytkownika, jak pokazano w tym przykładzie:

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "FUNCTION_URL", // Must be an `https` endpoint.
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

{
  "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 wejściowe użytkownika. Na przykład w przypadku pola tekstowego, w którym użytkownik wpisuje swoje imię i nazwisko, nazwa widżetu to contactName, a przykładowa wartość to Kai O.

Gdy użytkownik kliknie przycisk, aplikacja do obsługi czatu otrzyma obiekt zdarzenia, z którego możesz pobrać dane.

Odpowiadanie na przesłany formularz

Po otrzymaniu danych z wiadomości na karcie lub okna aplikacji do czatu odpowiada ona, potwierdzając otrzymanie danych lub zwracając błąd.

W tym przykładzie aplikacja do obsługi czatu wysyła wiadomość tekstową z potwierdzeniem, że otrzymała formularz przesłany z wiadomości na karcie.

/**
 * 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 payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } 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."
  }}}}};
}

/**
 * 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 określający, czy chcesz wysłać wiadomość z potwierdzeniem, zaktualizować pierwotną wiadomość lub kartę, czy tylko zamknąć okno. Instrukcje znajdziesz w artykule Zamykanie okna.

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub karta zwraca błąd, w interfejsie Google Chat pojawia się komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs Google Chat nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta Google Chat daje nieoczekiwany wynik, np. wiadomość na karcie może się nie pojawić.

Chociaż w interfejsie czatu może nie wyświetlać się komunikat o błędzie, opisowe komunikaty o błędach i dane logowania są dostępne, aby pomóc w naprawieniu błędów, gdy rejestrowanie błędów w aplikacjach na czat jest włączone. Pomoc dotyczącą wyświetlania, debugowania i naprawiania błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat.