Ta strona została przetłumaczona przez Cloud Translation API.

Otwórz interaktywne okna

Przedpremierowa wersja dla deweloperów: dostępna w ramach programu Google Workspace dla deweloperów, 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.

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

Ilustracja 1.: Aplikacja Google Chat otwiera okno dialogowe do zbierania informacji kontaktowych.

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

Wywołanie żądania dialogu w reakcji na interakcję z użytkownikiem.
Rozwiąż 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, np.:

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.
Reakcja na kliknięcie przycisku w wiadomości, czy to jako część karty, czy na dole 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.

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 znajduje się przykładowy plik JSON, który pokazuje, jak wywołać prośbę o dialog za pomocą 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 sections[]widżet. 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, która działa, 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 ButtonClickedPayload. W ładunku dialogEventType ma wartość SUBMIT_DIALOG.

Aplikacja Chat musi obsłużyć obiekt zdarzenia, wykonując jedną z tych czynności:

Zwracanie innego okna dialogowego, 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ść formularzy.

Aby przetworzyć dane wprowadzone przez użytkowników, aplikacja Google 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, 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 wartością buttonClickedPayload ustawioną na:

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:

UpdateMessageAction: zaktualizuje wiadomość wysłaną przez aplikację Google Chat, na przykład wiadomość, z której użytkownik poprosił o dialog.
UpdateInlinePreviewAction: zaktualizuje kartę z 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 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.