, 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
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żą.
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 commonEventObjectformInputs 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ść
textInputstringInputsevent.commonEventObject.formInputs.contactName.stringInputs.value[0]Kai O
selectionInputstringInputsAby uzyskać pierwszą lub jedyną wartość, event.commonEventObject.formInputs.contactType.stringInputs.value[0]
Personal
dateTimePicker, który akceptuje tylko daty.dateInputevent.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 actionParametersname 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 RenderActionsZamykanie 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 .
