Dostępna w ramach
, 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 pól formularza 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 Google Chat.
Wymagania wstępne
Node.js Dodatek do Google Workspace, który działa w Google Chat. Aby go utworzyć, wykonaj czynności opisane w krótkim przewodniku po HTTP .
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 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:
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 wyboru danych mogą też wypełniać i podpowiadać elementy z danych Google Workspace (np. z powierzchni czatu) lub z dynamicznego źródła danych. Szczegółowe informacje znajdziesz w sekcji Dodawanie menu z wieloma opcjami .
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 .
Dodawanie menu wyboru wielu elementów
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 z wieloma opcjami, które są rodzajem widżetu SelectionInput. Na przykład na tej karcie wyświetla się menu z wieloznacznikiem, w którym użytkownicy mogą dynamicznie wybierać kontakty z listy:
Elementy menu z wieloma opcjami możesz wypełniać z tych źródeł danych:
Dane Google Workspace , w tym użytkownicy lub pokoje czatu, których użytkownik jest członkiem. Menu wypełnia tylko elementy z tej samej organizacji Google Workspace.zewnętrznych źródeł danych , takich jak baza danych relacyjnych;
Możesz na przykład użyć menu z wieloma opcjami, aby ułatwić użytkownikowi wybór z listy potencjalnych klientów w systemie do 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, określ pole platformDataSourceSelectionInput. W przeciwieństwie do innych typów danych wyboru nie możesz pomijać obiektów SelectionItem
Podany niżej kod pokazuje menu z wieloma zaznaczeniami użytkowników Google Workspace.
Aby wypełnić listę użytkowników, dane wejściowe wyboru ustawiają commonDataSource na USER:
JSON
{
"selectionInput" : {
"name" : "contacts" ,
"type" : "MULTI_SELECT" ,
"label" : "Selected contacts" ,
"multiSelectMaxSelectedItems" : 5 ,
"multiSelectMinQueryLength" : 1 ,
"platformDataSource" : {
"commonDataSource" : "USER"
}
}
}
Poniższy kod pokazuje menu z wieloma opcjami wyboru w ChatSpaces. Aby wypełnić pola, pole wyboru określa pole hostAppDataSource. Menu wybierania wielu elementów ustawia też opcję defaultToCurrentSpace na true, co powoduje, że bieżący pokój jest domyślnie wybrany w menu:
JSON
{
"selectionInput" : {
"name" : "spaces" ,
"type" : "MULTI_SELECT" ,
"label" : "Selected contacts" ,
"multiSelectMaxSelectedItems" : 3 ,
"multiSelectMinQueryLength" : 1 ,
"platformDataSource" : {
"hostAppDataSource" : {
"chatDataSource" : {
"spaceDataSource" : {
"defaultToCurrentSpace" : true
}
}
}
}
}
}
Wypełnianie elementów z zewnętrznego źródła danych
Menu z wieloma opcjami mogą też wypełniać elementy z zewnętrznego źródła danych lub źródła danych firmy zewnętrznej. Aby używać zewnętrznego źródła danych, w widżecie SelectionInput podaj pole externalDataSource
Aby ograniczyć liczbę żądań wysyłanych do zewnętrznego źródła danych, możesz uwzględnić sugerowane elementy, które pojawiają się w menu wyboru wielokrotnego, zanim użytkownicy zaczną wpisywać w nim tekst. Możesz na przykład wypełnić kontakty ostatnio wyszukiwane przez użytkownika. Aby wypełnić sugerowane produkty z zewnętrznego źródła danych, podaj statyczne obiekty SelectionItem
Ten kod pokazuje menu z wieloma opcjami, które wysyła zapytanie o elementy z zewnętrznego źródła danych i wypełnia je:
JSON
{
"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 Sugerowanie elementów z wieloma opcjami .
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 elementu 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
Gdy aplikacja do obsługi czatu otrzyma dane, może:
W przypadku kart, które zawierają menu z wieloma opcjami wyboru, wypełniaj lub sugeruj elementy na podstawie tego, co użytkownik wpisze 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 wypełnił formularz.
Sugerowanie elementów z wieloma opcjami
Jeśli karta zawiera menu z wieloma opcjami, które wypełnia elementy ze źródła danych zewnętrznego , aplikacja Google 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 wyświetla miasta w Stanach Zjednoczonych, aplikacja Google Chat może automatycznie zaproponować Atlanta, zanim użytkownik skończy pisać. Aplikacja Czat może sugerować maksymalnie 100 elementów.
Aby sugerować i dynamicznie wypełniać elementy w menu z wielokrotnie wybieranymi opcjami, widget SelectionInput na karcie musi zawierać funkcję, która wysyła zapytanie do zewnętrznego źródła danych . Aby zwracać sugerowane elementy, funkcja musi:
Obsługuj obiekt zdarzenia , który aplikacja Google Chat otrzymuje, gdy użytkownicy wpisują coś w menu.
Z obiektu zdarzenia pobierz wartość wpisaną przez użytkownika, która jest reprezentowana w polu event.commonEventObject.parameters["autocomplete_widget_query"].
Przesyła zapytanie do źródła danych, używając wartości wprowadzonej przez użytkownika, aby uzyskać co najmniej jedną wartość SelectionItems, którą można zaproponować użytkownikowi.
Zwracaj sugerowane produkty, zwracając działanie RenderActionsmodifyCard.
Ten przykładowy kod pokazuje, jak aplikacja Google Chat dynamicznie sugeruje elementy w menu wielokrotnego wyboru na karcie. Gdy użytkownik wpisze coś w menu, funkcja lub punkt końcowy podany w polu externalDataSource widżetu wysyła zapytanie do zewnętrznego źródła danych i podpowiada użytkownikowi elementy, które może wybrać.
Node.js
/**
* 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
};
}
Zastąp FUNCTION_URL
Google Apps Script
/**
* 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ż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 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.
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 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."
}}}}};
}
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 Google Chat lub karta daje nieoczekiwany wynik. Na przykład może nie wyświetlić 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 pomogą Ci je naprawić. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami Google Chat .
