, który zapewnia wcześniejszy dostęp do niektórych funkcji.
Ta strona opisuje, jak aplikacja Google Chat może otwierać okna dialogowe, aby wyświetlać interfejsy użytkownika i na nie odpowiadać.
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 .
Dialogi to okna z interfejsami opartymi na kartach, które otwierają się z pokoju czatu lub wiadomości. Okno dialogowe i jego zawartość są widoczne tylko dla użytkownika, który je otworzył.
Aplikacje do czatu mogą używać dialogów do żądania i zbierania informacji od użytkowników czatu, w tym formularzy wieloetapowych. Więcej informacji o tworzeniu danych wejściowych formularza znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników .
Wymagania wstępne
Node.js dodatek do Google Workspace, który rozszerza Google Chat; Aby go utworzyć, wykonaj czynności opisane w krótkim przewodniku po HTTP .
Otwórz okno
Ilustracja 1. : Aplikacja Google Chat otwiera okno dialogowe do zbierania informacji kontaktowych.
W tej sekcji dowiesz się, jak odpowiadać i konfigurować dialogy:
Wywołanie żądania dialogu w reakcji na interakcję użytkownika.
Zaakceptuj prośbę, wracając do okna i otwierając okno dialogowe.
Gdy użytkownicy prześlą informacje, przetwórz przesłane dane, zamykając okno lub wyświetlając inne okno.
Wywołanie prośby o wyświetlenie okna
Aplikacja Google Chat może otwierać dialogy tylko w odpowiedzi na interakcję użytkownika, taką jak polecenie po ukośniku lub kliknięcie przycisku w wiadomości na karcie.
Aby odpowiadać użytkownikom za pomocą dialogu, aplikacja do czatu musi stworzyć interakcję, która uruchamia prośbę o dialog, na przykład:
Odpowiadanie na polecenie po ukośniku Aby wywołać prośbę z polecenia z ukośnikiem, podczas konfigurowania polecenia musisz zaznaczyć pole wyboru Otwieranie okna dialogowego .Reakcja na kliknięcie przycisku w wiadomości ,
czy to jako część karty, czy u dołu wiadomości. Aby wywołać prośbę za pomocą przycisku w wiadomości, skonfiguruj działanie onClickinteraction na OPEN_DIALOG.
Rysunek 2. : Aplikacja Google Chat wysyła wiadomość z prośbą o użycie polecenia /addContact.
Poniższy plik JSON pokazuje, jak wywołać prośbę o dialog za pomocą przycisku w wiadomości z kartą. Aby otworzyć okno, ustaw wartość pola onClick.action.interactionOPEN_DIALOG:
{
"buttonList" : { "buttons" : [{
"text" : "BUTTON_TEXT " ,
"onClick" : { "action" : {
"function" : "ACTION_FUNCTION " ,
"interaction" : "OPEN_DIALOG"
}}
}]}
}
Gdzie BUTTON_TEXT to tekst wyświetlany na przycisku, a ACTION_FUNCTION to funkcja, która uruchamia początkowy dialog.
Otwórz pierwsze okno dialogowe
Gdy użytkownik wywoła prośbę o dialog, aplikacja do obsługi czatu otrzyma obiekt zdarzenia z ładunkiem, który określa, że obiekt dialogEventType to REQUEST_DIALOG.
Aby otworzyć okno dialogowe, aplikacja Google Chat może odpowiedzieć na prośbę, zwracając obiekt RenderActionspushCard, aby wyświetlić kartę. Karta powinna zawierać dowolne elementy interfejsu, w tym co najmniej 1 widżetsections[]Zbieranie i przetwarzanie informacji od użytkowników .
Ten plik JSON pokazuje, jak aplikacja Google Chat zwraca odpowiedź, która otwiera okno dialogowe:
{
"action" : { "navigations" : [{ "pushCard" : { "sections" : [{ "widgets" : [{
WIDGETS ,
{ "buttonList" : { "buttons" : [{
"text" : "BUTTON_TEXT " ,
"onClick" : {
"action" : { "function" : "ACTION_FUNCTION " }
}
}]}}
}]}]}}]}
}
Gdzie BUTTON_TEXT to tekst wyświetlany na przycisku (np. Next lub Submit), WIDGETS to co najmniej 1 element formularza do wprowadzania danych , a ACTION_FUNCTION to funkcja wywołania zwrotnego akcji, która jest wykonywana, gdy użytkownik kliknie przycisk.
Obsługa przesyłania okna
Gdy użytkownicy klikną przycisk, który przesyła okno dialogowe, aplikacja czatu otrzyma obiekt zdarzenia z obiektem ButtonClickedPayloaddialogEventType ma wartość SUBMIT_DIALOG.
Aplikacja Chat musi obsłużyć obiekt zdarzenia, wykonując jedną z tych czynności:
Zwracanie innego okna , aby wypełnić inną kartę lub formularz.Zamknij okno po zweryfikowaniu danych przesłanych przez użytkownika i opcjonalnie wyślij wiadomość z potwierdzeniem.
Opcjonalnie: zwracanie innego okna
Po przesłaniu przez użytkowników początkowego okna dialogowego aplikacje do czatu mogą wyświetlić jedno lub więcej dodatkowych okien, aby pomóc im sprawdzić informacje przed przesłaniem, wypełnić formularze wieloetapowe lub dynamicznie wypełnić zawartość formularza.
Aby przetworzyć dane wprowadzone przez użytkowników, aplikacja Chat obsługuje dane w obiekcie zdarzenia commonEventObject.formInputsZbieranie i przetwarzanie informacji o użytkownikach .
Aby śledzić dane wprowadzane przez użytkowników w pierwszym oknie, musisz dodać parametry do przycisku, który otwiera następne okno. Szczegółowe informacje znajdziesz w artykule Przenoszenie danych na inną kartę .
W tym przykładzie aplikacja do czatu otwiera pierwsze okno dialogowe, które prowadzi do drugiego okna z potwierdzeniem przed przesłaniem:
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 ;
// Handle MESSAGE events
if ( chatEvent . messagePayload ) {
return res . send ( handleMessage ( req . body ));
// Handle button clicks
} else if ( chatEvent . buttonClickedPayload ) {
switch ( req . body . commonEventObject . parameters . actionName ) {
case "openInitialDialog" :
return res . send ( openInitialDialog ( req . body ));
case "openConfirmationDialog" :
return res . send ( openConfirmationDialog ( req . body ));
case "submitDialog" :
return res . send ( submitDialog ( req . body ));
}
}
};
/**
* Responds to a message in Google Chat.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} response that handles dialogs.
*/
function handleMessage ( event ) {
// Reply with a message that contains a button to open the initial dialog
return { hostAppDataAction : { chatDataAction : { createMessageAction : { message : {
text : "To add a contact, use the `ADD CONTACT` button below." ,
accessoryWidgets : [{ buttonList : { buttons : [{
text : "ADD CONTACT" ,
onClick : { action : {
// Use runtime environment variable set with self URL
function : process . env . BASE_URL ,
parameters : [{ key : "actionName" , value : "openInitialDialog" }],
interaction : "OPEN_DIALOG"
}}
}]}}]
}}}}};
}
/**
* Opens the initial step of the dialog that lets users add contact details.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} open the dialog.
*/
function openInitialDialog ( event ) {
return { action : { navigations : [{ pushCard : { sections : [{ widgets : [{
textInput : {
name : "contactName" ,
label : "First and last name" ,
type : "SINGLE_LINE"
}},
WIDGETS , {
buttonList : { buttons : [{
text : "NEXT" ,
onClick : { action : {
// Use runtime environment variable set with self URL
function : process . env . BASE_URL ,
parameters : [{ key : "actionName" , value : "openConfirmationDialog" }]
}}
}]}}
]}]}}]}};
}
/**
* Opens the second step of the dialog that lets users confirm details.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} update the dialog.
*/
function openConfirmationDialog ( event ) {
// Retrieve the form input values
const name = event . commonEventObject . formInputs [ "contactName" ]. stringInputs . value [ 0 ];
return { action : { navigations : [{ pushCard : { sections : [{ widgets : [{
// Display the input values for confirmation
textParagraph : { text : "<b>Name:</b> " + name }},
WIDGETS , {
buttonList : { buttons : [{
text : "SUBMIT" ,
onClick : { action : {
// Use runtime environment variable set with self URL
function : process . env . BASE_URL ,
parameters : [{
key : "actionName" , value : "submitDialog" }, {
// Pass input values as parameters for last dialog step (submission)
key : "contactName" , value : name
}]
}}
}]}}]
}]}}]}};
}
Google Apps Script
W tym przykładzie wysyłamy wiadomość z karty, zwracając obiekt JSON karty .
Możesz też użyć usługi karty w Apps Script .
/**
* Responds to a message in Google Chat.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} response that handles dialogs.
*/
function onMessage ( event ) {
// Reply with a message that contains a button to open the initial dialog
return { hostAppDataAction : { chatDataAction : { createMessageAction : { message : {
text : "To add a contact, use the `ADD CONTACT` button below." ,
accessoryWidgets : [{ buttonList : { buttons : [{
text : "ADD CONTACT" ,
onClick : { action : {
function : "openInitialDialog" ,
interaction : "OPEN_DIALOG"
}}
}]}}]
}}}}};
}
/**
* Opens the initial step of the dialog that lets users add contact details.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} open the dialog.
*/
function openInitialDialog ( event ) {
return { action : { navigations : [{ pushCard : { sections : [{ widgets : [{
textInput : {
name : "contactName" ,
label : "First and last name" ,
type : "SINGLE_LINE"
}},
WIDGETS , {
buttonList : { buttons : [{
text : "NEXT" ,
onClick : { action : { function : "openConfirmationDialog" }}
}]}}
]}]}}]}};
}
/**
* Opens the second step of the dialog that lets users confirm details.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} update the dialog.
*/
function openConfirmationDialog ( event ) {
// Retrieve the form input values
const name = event . commonEventObject . formInputs [ "contactName" ]. stringInputs . value [ 0 ];
return { action : { navigations : [{ pushCard : { sections : [{ widgets : [{
// Display the input values for confirmation
textParagraph : { text : "<b>Name:</b> " + name }},
WIDGETS , {
buttonList : { buttons : [{
text : "SUBMIT" ,
onClick : { action : {
function : "submitDialog" ,
// Pass input values as parameters for last dialog step (submission)
parameters : [{ key : "contactName" , value : name }]
}}
}]}}]
}]}}]}};
}
Gdzie WIDGETS reprezentuje dowolne inne widżety wprowadzania danych .
Zamknij okno
Gdy użytkownicy klikną przycisk przesyłania w oknie dialogowym, aplikacja Google Chat wykona powiązane z nim działanie i przekaże obiekt zdarzenia z parametrem buttonClickedPayload o tej wartości:
isDialogEvent to true.dialogEventType to SUBMIT_DIALOG.
Aplikacja Google Chat powinna zwrócić obiekt RenderActionsEndNavigationCLOSE_DIALOG.
Opcjonalnie: wyświetl powiadomienie
Po zamknięciu okna możesz też wyświetlić powiadomienie tekstowe.
Aby wyświetlić powiadomienie, zwracaj obiekt RenderActionsnotification.
W tym przykładzie sprawdzamy, czy parametry są prawidłowe, i zamykamy okno z powiadomieniem tekstowym w zależności od wyniku:
Node.js
/**
* Handles submission and closes the dialog.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} close the dialog with a status in text notification.
*/
function submitDialog ( event ) {
// Validate the parameters.
if ( ! event . commonEventObject . parameters [ "contactName" ]) {
return { action : {
navigations : [{ endNavigation : "CLOSE_DIALOG" }],
notification : { text : "Failure, the contact name was missing!" }
}};
}
return { action : {
navigations : [{ endNavigation : "CLOSE_DIALOG" }],
notification : { text : "Success, the contact was added!" }
}};
}
Google Apps Script
/**
* Handles submission and closes the dialog.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} close the dialog with a status in text notification.
*/
function submitDialog ( event ) {
// Validate the parameters.
if ( ! event . commonEventObject . parameters [ "contactName" ]) {
return { action : {
navigations : [{ endNavigation : "CLOSE_DIALOG" }],
notification : { text : "Failure, the contact name was missing!" }
}};
}
return { action : {
navigations : [{ endNavigation : "CLOSE_DIALOG" }],
notification : { text : "Success, the contact was added!" }
}};
}
Szczegółowe informacje o przekazywaniu parametrów między dialogami znajdziesz w artykule Przenoszenie danych na inną kartę .
Opcjonalnie: wysyłaj wiadomość z potwierdzeniem
Po zamknięciu okna możesz też wysłać nową wiadomość lub zaktualizować istniejącą.
Aby wysłać nową wiadomość, zwróć obiekt DataActionsCreateMessageAction ustawionym na nową wiadomość. Aby na przykład zamknąć okno i wysłać SMS-a, zwracaj:
{ "hostAppDataAction" : { "chatDataAction" : { "createMessageAction" : { "message" : {
"text" : "Your information has been submitted."
}}}}}
Aby zaktualizować wiadomość po przesłaniu przez użytkownika okna dialogowego, zwróć obiekt DataActions zawierający jedną z tych czynności:
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 .
