Otwórz interaktywne okna

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.

Google Apps Script

dodatek do Google Workspace, który rozszerza Google Chat; Aby utworzyć taki projekt, zapoznaj się z krótkim przewodnikiem po Apps Script.

Otwórz okno

Okno z różnymi widżetami.
Ilustracja 1.: Aplikacja Google Chat otwiera okno dialogowe do zbierania informacji kontaktowych.

W tej sekcji opisaliśmy, jak odpowiadać na pytania i jak konfigurować dialog:

  1. Wywołanie żądania dialogu w reakcji na interakcję z użytkownikiem.
  2. Rozwiąż prośbę, wracając do okna i otwierając okno dialogowe.
  3. Gdy użytkownicy prześlą informacje, przetwórz dane, zamykając okno lub wyświetlając inne okno.

Wywołanie prośby o wyświetlenie okna

Aplikacja Google Chat może otwierać okna dialogowe tylko w odpowiedzi na interakcję użytkownika, taką jak szybkie polecenie, 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 szybkie polecenia lub polecenia po ukośniku. Aby wywołać żądanie z poziomu szybkiego polecenia lub polecenia po ukośniku, podczas konfigurowania szybkiego polecenia lub polecenia po ukośniku 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 onClick przycisku, ustawiając wartość parametru interaction na OPEN_DIALOG.
Przycisk wywołujący okno
Rysunek 2.: Aplikacja Google Chat wysyła wiadomość z prośbą o użycie polecenia /addContact.
Wiadomość zawiera też przycisk, który użytkownicy mogą kliknąć, aby wywołać polecenie.

Poniżej znajdziesz przykład kodu JSON, który pokazuje, jak wywołać prośbę o dialog z poziomu przycisku w wiadomości z kartą. Aby otworzyć okno, ustaw wartość pola 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 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 RenderActions z nawigacją pushCard, aby wyświetlić kartę. Karta powinna zawierać dowolne elementy interfejsu, w tym co najmniej 1 widżetsections[]. Aby zbierać informacje od użytkowników, możesz użyć widżetów formularza i widżetu przycisku. Więcej informacji o projektowaniu pól formularza znajdziesz w artykule 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, Twoja aplikacja czatu otrzyma obiekt zdarzenia z obiektem ButtonClickedPayload. W ładunku dialogEventType ma wartość SUBMIT_DIALOG.

Aplikacja Google 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 ich przesłaniem, wypełnić formularze wieloetapowe lub dynamicznie wypełnić zawartość formularzy.

Aby przetworzyć dane wprowadzone przez użytkowników, aplikacja Chat obsługuje dane w obiekcie zdarzenia commonEventObject.formInputs. Więcej informacji o pobieraniu wartości z widżetów z danymi wejściowymi znajdziesz w artykule Zbieranie i przetwarzanie informacji o użytkownikach.

Aby śledzić dane wprowadzane przez użytkowników w pierwszym oknie dialogowym, 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 RenderActions, w którym EndNavigationma wartość CLOSE_DIALOG.

Opcjonalnie: wyświetl powiadomienie

Po zamknięciu okna możesz też wyświetlić powiadomienie tekstowe.

Aby wyświetlić powiadomienie, zwracaj 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

/**
 * 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 DataActions z polem CreateMessageAction 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 Google Chat lub karta powoduje 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 poprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami Google Chat.