Tworzenie interaktywnych dialogów

Na tej stronie dowiesz się, jak aplikacja Google Chat może otwierać okna, aby wyświetlać interfejsy i odpowiadać na działania użytkowników.

Uwaga: w Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Aplikację do obsługi Google Chat możesz też utworzyć za pomocą wydarzeń interakcji interfejsu Google Chat API. Więcej informacji znajdziesz w artykule Rozszerzanie Google Chat – omówienie.

Okna dialogowe to interfejsy okienkowe oparte 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ć okien dialogowych, aby prosić użytkowników Google Chat o informacje i je zbierać, w tym formularze wieloetapowe. Więcej informacji o tworzeniu pól formularza znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników.

Wymagania wstępne

HTTP

Dodatek do Google Workspace, który rozszerza funkcje Google Chat. Aby go utworzyć, wykonaj czynności opisane w tym przewodniku.

Uwaga: przykłady kodu w tym przewodniku są napisane tak, aby działały jako funkcja Google Cloud Run dla Node.js.

Google Apps Script

Dodatek do Google Workspace, który rozszerza funkcje Google Chat. Aby utworzyć taki skrypt, wykonaj czynności opisane w krótkim przewodniku po Apps Script.

Otwórz okno

Ilustracja 1. Aplikacja Google Chat, która otwiera okno dialogowe do zbierania informacji kontaktowych.

W tej sekcji dowiesz się, jak odpowiadać na wiadomości i konfigurować okno dialogowe, wykonując te czynności:

1. Wywołaj prośbę o okno z interakcji użytkownika.
2. Obsłuż żądanie, wracając do okna i otwierając je.
3. Po przesłaniu przez użytkowników informacji przetwórz je, zamykając okno lub wyświetlając inne okno.

Wywoływanie prośby o okno

Aplikacja Google Chat może otwierać okna tylko w odpowiedzi na interakcję użytkownika, np. polecenie lub kliknięcie przycisku w wiadomości na karcie.

Aby odpowiadać użytkownikom za pomocą okna, aplikacja do obsługi czatu musi utworzyć interakcję, która wywołuje żądanie okna, np.:

• Odpowiadaj na polecenia. Aby wywołać żądanie za pomocą polecenia, podczas konfigurowania polecenia musisz zaznaczyć pole wyboru Otwiera okno.
• Odpowiadanie na kliknięcie przycisku w wiadomości, w ramach karty lub u dołu wiadomości. Aby wywołać żądanie za pomocą przycisku w wiadomości, skonfiguruj działanie onClick przycisku, ustawiając jego parametr interaction na OPEN_DIALOG.

Ilustracja 2. Aplikacja Google Chat wysyła wiadomość, która zachęca użytkowników do użycia /addContact polecenia z ukośnikiem.
Wiadomość zawiera też przycisk, który użytkownicy mogą kliknąć, aby wywołać polecenie.

Poniższy kod JSON pokazuje, jak wywołać żądanie okna z przycisku w wiadomości na karcie. Aby otworzyć okno, ustaw pole onClick.action.interaction przycisku na OPEN_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 otwiera początkowe okno dialogowe. W przypadku dodatków utworzonych przy użyciu punktów końcowych HTTP element ACTION_FUNCTION powinien wskazywać pełny adres URL HTTP punktu końcowego.

Otwórz pierwsze okno dialogowe

Gdy użytkownik wywoła żądanie okna, aplikacja do obsługi czatu otrzyma obiekt zdarzenia z ładunkiem, który określa, że obiekt dialogEventType jest obiektem REQUEST_DIALOG.

Aby otworzyć okno, aplikacja Chat może odpowiedzieć na żądanie, zwracając obiekt RenderActions z nawigacją pushCard, aby wyświetlić kartę. Karta powinna zawierać elementy interfejsu, w tym co najmniej 1 sections[] widżet. Aby zbierać informacje od użytkowników, możesz określić widżety wprowadzania danych w formularzu i widżet przycisku. Więcej informacji o projektowaniu pól formularza znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników.

Poniższy kod JSON pokazuje, jak aplikacja w Google Chat zwraca odpowiedź, która otwiera okno:

{
  "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 widżet wprowadzania danych w formularzu, a ACTION_FUNCTION to funkcja wywołania zwrotnego działania, która jest uruchamiana, gdy użytkownicy klikną przycisk. W przypadku punktów końcowych HTTP powinien on wskazywać pełny adres URL HTTP.

Obsługa przesłania okna

Gdy użytkownicy klikną przycisk, który przesyła okno, aplikacja do obsługi czatu otrzyma obiekt zdarzenia z obiektem ButtonClickedPayload. W ładunku wartość parametru dialogEventType jest ustawiona na SUBMIT_DIALOG. Aby dowiedzieć się, jak zbierać i przetwarzać informacje w oknie, przeczytaj artykuł Zbieranie i przetwarzanie informacji od użytkowników Google Chat.

Aplikacja Google Chat musi odpowiedzieć na obiekt zdarzenia, wykonując jedną z tych czynności:

• Zwróć kolejne okno, aby wypełnić kolejną kartę lub formularz.
• Zamknij okno po sprawdzeniu danych przesłanych przez użytkownika i opcjonalnie wyślij wiadomość z potwierdzeniem.

Opcjonalnie: zwracanie innego okna

Po przesłaniu początkowego okna dialogowego aplikacje w Chat mogą zwracać jedno lub więcej dodatkowych okien dialogowych, aby pomóc użytkownikom w sprawdzeniu informacji przed przesłaniem, wypełnianiu formularzy wieloetapowych lub dynamicznym wypełnianiu treści formularza.

Aby przetwarzać dane wprowadzane przez użytkowników, aplikacja Chat obsługuje je w obiekcie commonEventObject.formInputs zdarzenia. Więcej informacji o pobieraniu wartości z widżetów wejściowych znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników.

Aby śledzić dane wprowadzane przez użytkowników w początkowym oknie, musisz dodać parametry do przycisku, który otwiera następne okno. Więcej informacji znajdziesz w sekcji Przenoszenie danych na inną kartę.

W tym przykładzie aplikacja do obsługi czatu otwiera początkowe okno, które prowadzi do drugiego okna z prośbą o potwierdzenie przed przesłaniem:

Node.js

Uwaga: przykłady kodu w tym przewodniku są napisane tak, aby działały jako funkcja Google Cloud Run dla Node.js.

/**
 * Google Cloud Run 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łana jest wiadomość z kartą przez zwrócenie kodu JSON karty. Możesz też użyć usługi kart 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 oznacza dowolny inny widżet wprowadzania danych w formularzu.

Zamknij okno

Gdy użytkownicy klikną przycisk przesyłania w oknie dialogowym, aplikacja do czatu wykona powiązane z nim działanie i przekaże obiekt zdarzenia z parametrem buttonClickedPayload ustawionym na:

• isDialogEvent to true.
• dialogEventType to SUBMIT_DIALOG.

Aplikacja Chat powinna zwrócić obiekt RenderActions z ustawioną wartością CLOSE_DIALOG w polu EndNavigation.

Opcjonalnie: wyświetlanie tymczasowego powiadomienia

Po zamknięciu okna możesz też wyświetlić użytkownikowi, który wchodzi w interakcję z aplikacją, tymczasowe powiadomienie tekstowe.

Aby wyświetlić powiadomienie, zwróć obiekt RenderActions z ustawionym polem notification.

W tym przykładzie sprawdzamy, czy parametry są prawidłowe, i zamykamy okno z powiadomieniem tekstowym w zależności od wyniku:

Node.js

Uwaga: przykłady kodu w tym przewodniku są napisane tak, aby działały jako funkcja Google Cloud Run dla 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: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: { action: "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: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: {action: "CLOSE_DIALOG"}}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Szczegółowe informacje o przekazywaniu parametrów między oknami znajdziesz w artykule Przekazywanie danych na inną kartę.

Opcjonalnie: wysyłanie wiadomości z potwierdzeniem na czacie

Po zamknięciu okna możesz też wysłać nową wiadomość na czacie lub zaktualizować istniejącą.

Aby wysłać nową wiadomość, zwróć obiekt DataActions z polem CreateMessageAction ustawionym na nową wiadomość. Aby na przykład zamknąć okno i wysłać SMS-a, zwróć te wartości:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

Aby zaktualizować wiadomość po przesłaniu przez użytkownika okna, zwróć obiekt DataActions, który zawiera jedno z tych działań:

• UpdateMessageAction:aktualizuje wiadomość wysłaną przez aplikację do obsługi czatu, np. wiadomość, z której użytkownik poprosił o wyświetlenie okna.
• UpdateInlinePreviewAction: aktualizuje kartę na podstawie podglądu linku.

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