Tworzenie strony głównej aplikacji Google Chat

Na tej stronie dowiesz się, jak utworzyć stronę główną dla wiadomości bezpośrednich w aplikacji Google Chat. Strona główna, w interfejsie Google Chat API nazywana stroną aplikacji, to karta z interfejsem, którą można dostosować. Wyświetla się ona na karcie Strona główna w czatach indywidualnych między użytkownikiem a aplikacją Google Chat.

Ilustracja 1. Przykład strony głównej, która pojawia się w wiadomościach bezpośrednich z aplikacją Google Chat.

W przeciwieństwie do innych aplikacji hostujących Google Workspace dodatki rozszerzające Chat nie wyświetlają strony głównej w panelu szybkiego dostępu po prawej stronie i nie używają addOns.common.homepageTrigger w pliku manifestu. Zamiast tego Google Chat wyświetla Twoją stronę główną jako kartę na karcie Strona główna w czacie indywidualnym z aplikacją Google Chat. Jest ona skonfigurowana w konsoli Google Cloud.

Strona główna aplikacji umożliwia udostępnianie wskazówek dotyczących interakcji z aplikacją Google Chat, wyświetlanie spersonalizowanego panelu użytkownika lub umożliwianie użytkownikom dostępu do usługi lub narzędzia zewnętrznego i konfigurowania ich z poziomu Google Chat.

---

Użyj narzędzia do tworzenia kart, aby projektować i wyświetlać podgląd wiadomości oraz interfejsów użytkownika w aplikacjach do obsługi czatu:

Otwórz narzędzie do tworzenia kart

---

Wymagania wstępne

HTTP

Aplikacja Google Chat, która odbiera i odpowiada na interakcje użytkowników. Aby go utworzyć, wykonaj czynności opisane w krótkim wprowadzeniu do HTTP.

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

Aplikacja Google Chat, która odbiera i odpowiada na interakcje użytkowników. Aby utworzyć taki skrypt, wykonaj czynności opisane w krótkim wprowadzeniu do Apps Script.

Konfigurowanie strony głównej aplikacji w Google Chat

Aby obsługiwać stronę aplikacji, włącz opcję Obsługa strony aplikacji i skonfiguruj stronę aplikacji jako wyzwalacz w konsoli Google Cloud. Aplikacja Google Chat otrzymuje zdarzenie wywołujące Strona aplikacji, gdy użytkownik otwiera kartę Strona główna w czacie indywidualnym 1:1 z aplikacją Google Chat.

Aby skonfigurować stronę główną aplikacji w konsoli Google Cloud:

1. W konsoli Google Cloud kliknij Menu > Interfejsy API i usługi > Włączone interfejsy API i usługi > Google Chat API > Konfiguracja.

   Otwórz konfigurację interfejsu Chat API

2. W sekcji Funkcje interaktywne sprawdź, czy opcja Włącz funkcje interaktywne jest włączona, a następnie w sekcji Funkcje zaznacz pole wyboru Strona główna aplikacji pomocy.

3. W sekcji Ustawienia połączenia > Triggery w polu Strona główna aplikacji określ procedurę obsługi strony głównej aplikacji na podstawie architektury aplikacji do Google Chat:

   • HTTP: wpisz adres URL punktu końcowego HTTPS, który obsługuje żądania strony głównej aplikacji (lub kliknij Używaj wspólnego adresu URL punktu końcowego HTTP dla wszystkich aktywatorów, aby wspólny adres URL punktu końcowego HTTP otrzymywał wszystkie zdarzenia).
   • Google Apps Script: wpisz nazwę wywołania zwrotnego Google Apps Script, które tworzy i zwraca kartę strony głównej (domyślnie onAppHome).

4. Kliknij Zapisz.

Obsługa obiektu zdarzenia Strona główna aplikacji

Gdy użytkownik otworzy kartę Strona główna na czacie indywidualnym z aplikacją Google Chat, Google Chat wyśle obiekt zdarzenia do punktu końcowego Strony głównej aplikacji lub funkcji wywołania zwrotnego.

W przeciwieństwie do zdarzeń interakcji z przestrzenią lub wiadomością początkowy obiekt zdarzenia Strona główna aplikacji nie zawiera ładunku interakcji typu union (np. messagePayload). Zawiera te pola:

• commonEventObject: obejmuje clientPlatform, hostApp ("CHAT"), userLocale i userTimezone.
• chat.user: użytkownik Google Chat, który otworzył kartę Główna.
• chat.eventTime: sygnatura czasowa otwarcia przez użytkownika karty Strona główna.

Tworzenie karty ekranu głównego aplikacji

Gdy użytkownik otworzy kartę Główna, obsłuż zdarzenie wywołujące stronę główną aplikacji, zwracając obiekt RenderActions z działaniem pushCardnawigacji i obiektem Card. Aby utworzyć interaktywne treści, karta może zawierać interaktywne widżety, takie jak przyciski lub pola tekstowe.

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                },
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "Refresh",
                        "onClick": {
                          "action": {
                            "function": "https://example.com/updateAppHome"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

/**
 * Builds and returns the App Home card when a user opens the Home tab.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response pushing the homepage card.
 */
function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection()
              .addWidget(
                  CardService.newTextParagraph().setText(
                      'Manage your settings and view your dashboard here.'))
              .addWidget(
                  CardService.newButtonSet().addButton(
                      CardService.newTextButton()
                          .setText('Refresh')
                          .setOnClickAction(
                              CardService.newAction().setFunctionName(
                                  'updateAppHome')))))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Odpowiadanie na interakcje w aplikacji Home

Jeśli karta strony głównej aplikacji zawiera interaktywne widżety, takie jak przyciski lub pola formularza, kliknięcie przycisku wysyła obiekt zdarzenia zawierający chat.buttonClickedPayload (wraz z commonEventObject.parameters i commonEventObject.formInputs) do skonfigurowanej funkcji działania lub punktu końcowego przycisku.

Aby zaktualizować kartę Strona aplikacji w odpowiedzi na interakcję użytkownika, zwróć obiekt RenderActions z działaniem updateCard navigation. Więcej informacji o odczytywaniu danych wejściowych z formularzy w interaktywnych widżetach znajdziesz w artykule Odczytywanie danych z formularzy wprowadzonych przez użytkowników na kartach.

HTTP

{
  "action": {
    "navigations": [
      {
        "updateCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Last updated: 2026-10-02T23:00:00Z"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

/**
 * Updates the App Home card when a user clicks the Refresh button.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response updating the homepage card.
 */
function updateAppHome(event) {
  const updatedCard = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Last updated: ' + new Date().toTimeString())))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();
}

Otwieranie okien z poziomu strony głównej aplikacji

Aplikacja Google Chat może też odpowiadać na interakcje na stronie głównej aplikacji, otwierając okna dialogowe.

Ilustracja 2. Okno dialogowe z prośbą o dodanie kontaktu.

Aby dowiedzieć się, jak otwierać, aktualizować i zamykać okna dialogowe za pomocą RenderActions(pushCard, updateCard i endNavigation: "CLOSE_DIALOG"), przeczytaj artykuł Otwieranie interaktywnych okien dialogowych.

Powiązane artykuły

• Otrzymywanie odpowiedzi na interakcje użytkowników
• Otwieranie interaktywnych okien
• Odczytywanie danych z formularza wprowadzonych przez użytkowników na kartach
• Wyświetlanie przykładowych aplikacji do Google Chat

Aplikacje do obsługi czatu, które nie są dodatkami: tworzenie strony głównej aplikacji do obsługi czatu

Jeśli utrzymujesz aplikację do obsługi czatu, która nie jest dodatkiem do Google Workspace, Chat wysyła APP_HOMEzdarzenie interakcji, gdy użytkownik otworzy kartę Główna, oraz zdarzenia interakcji CARD_CLICKED lub SUBMIT_FORM, gdy użytkownik wejdzie w interakcję z widżetami na karcie Główna aplikacji.

Aby przekształcić aplikację do czatu, która nie jest dodatkiem, w dodatek do Google Workspace, zapoznaj się z artykułem Przekształcanie aplikacji do Google Chat w dodatek do Google Workspace.

Tworzenie karty Strona aplikacji w aplikacji do czatu, która nie jest dodatkiem

W aplikacji do Google Chat, która nie jest dodatkiem, obsłuż zdarzenie interakcji APP_HOME, zwracając odpowiedź zawierającą pole najwyższego poziomu renderActions z pushCard nawigacją:

Node.js

node/app-home/index.js

Wyświetl w GitHubie

app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py

Wyświetl w GitHubie

@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

Wyświetl w GitHubie

// Process Google Chat events
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

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.

apps-script/app-home/app-home.gs

Wyświetl w GitHubie

/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Odpowiadanie na interakcje na stronie głównej aplikacji w aplikacji do Google Chat, która nie jest dodatkiem

W aplikacji Google Chat, która nie jest dodatkiem, obsługuj zdarzenia interakcji CARD_CLICKED lub SUBMIT_FORM z karty Strona główna aplikacji, zwracając odpowiedź zawierającą pole najwyższego poziomu renderActions z updateCard nawigacją:

Node.js

node/app-home/index.js

Wyświetl w GitHubie

// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py

Wyświetl w GitHubie

def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

Wyświetl w GitHubie

// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

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.

apps-script/app-home/app-home.gs

Wyświetl w GitHubie

/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}