Tworzenie strony głównej aplikacji Google Chat

Na tej stronie znajdziesz instrukcje tworzenia strony głównej wiadomości bezpośrednich w aplikacji Google Chat. Strona główna, zwana w interfejsie Google Chat API stroną główną aplikacji, to konfigurowalny interfejs karty, który pojawia się na karcie Główna pomieszczeń wiadomości bezpośrednich między użytkownikiem a aplikacją Google Chat.

Karta główna aplikacji z 2 widżetami.
Rysunek 1. Przykład strony głównej wyświetlanej na czacie w aplikacji Google Chat.

Na stronie głównej aplikacji możesz udostępniać porady dotyczące interakcji z aplikacją Google Chat lub zezwalać użytkownikom na dostęp do usługi lub narzędzia zewnętrznego w Google Chat.


Za pomocą kreatora kart możesz zaprojektować i wyświetlić podgląd komunikatów oraz interfejsów użytkownika aplikacji do obsługi czatu:

Otwórz kreatora kart

Wymagania wstępne

Node.js

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywną aplikację Google Chat przy użyciu usługi HTTP, wykonaj to krótkie wprowadzenie.

Python

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywna aplikacja do obsługi czatu przy użyciu usługi HTTP zapoznaj się z tym krótkim wprowadzeniem.

Java

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywna aplikacja do obsługi czatu przy użyciu usługi HTTP zapoznaj się z tym krótkim wprowadzeniem.

Google Apps Script

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywną aplikację Google Chat w Apps Script, wykonaj te czynności.

Konfigurowanie ekranu głównego aplikacji Google Chat

Aby umożliwić korzystanie z ekranu głównego aplikacji, musisz skonfigurować aplikację Google Chat tak, aby odbierała APP_HOME zdarzenia interakcji. Aplikacja Google Chat otrzymuje to zdarzenie za każdym razem, gdy użytkownik kliknie kartę Ekran główny w aplikacji Google Chat.

Aby zaktualizować ustawienia konfiguracji w konsoli Google Cloud, wykonaj te czynności:

  1. W konsoli Google Cloud otwórz Menu > Więcej usług > Google Workspace > Biblioteka usług > Google Chat API.

    Otwórz interfejs Google Chat API

  2. Kliknij Zarządzaj, a następnie kartę Konfiguracja.

  3. W sekcji Funkcje interaktywne otwórz sekcję Funkcje, aby skonfigurować stronę główną aplikacji:

    1. Zaznacz pole wyboru Odbieranie wiadomości 1:1.
    2. Zaznacz pole wyboru Pomoc techniczna App Home.
  4. Jeśli Twoja aplikacja do czatu korzysta z usługi HTTP, otwórz Ustawienia połączenia i w polu Adres URL strony głównej aplikacji podaj punkt końcowy. Możesz użyć tego samego adresu URL, który został podany w polu URL punktu końcowego HTTP.

  5. Kliknij Zapisz.

Utwórz kartę strony głównej aplikacji

Gdy użytkownik otworzy ekran główny aplikacji, aplikacja Google Chat musi obsłużyć zdarzenie interakcji APP_HOME przez zwrócenie wystąpienia RenderActions z nawigacją pushCard i Card Aby stworzyć interaktywną kartę, możesz użyć interaktywnych widżetów, takich jak przyciski lub pola tekstowe, które aplikacja czatu może przetwarzać i na które może odpowiadać dodatkowymi kartami lub oknem dialogowym.

W przykładzie poniżej aplikacja Google Chat wyświetla pierwszą kartę strony głównej aplikacji, która zawiera godzinę utworzenia karty oraz przycisk. Gdy użytkownik kliknie przycisk, aplikacja Czat zwróci zaktualizowaną kartę z czasem jej utworzenia.

Node.js

node/app-home/index.js
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
@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
/**
 * Process Google Chat events
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@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() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

Google Apps Script

Zaimplementuj funkcję onAppHome, która jest wywoływana po wszystkich zdarzeniach interakcji APP_HOME:

W tym przykładzie wysyłamy wiadomość z karty, zwracając obiekt JSON karty. Możesz też użyć usługi Usługa karty Apps Script.

apps-script/app-home/app-home.gs
/**
 * 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"
      }}
    }]}}
  ]}]};
}

reagować na interakcje z ekranem głównym aplikacji,

Jeśli początkowa karta aplikacji zawiera interaktywne widżety, takie jak przyciski lub pola wyboru, aplikacja Chat musi obsługiwać powiązane zdarzenia interakcji, zwracając wystąpienieRenderActions z navigacją updateCard. Więcej informacji o obsługiwaniu widżetów interaktywnych znajdziesz w artykule Przetwarzanie informacji wprowadzanych przez użytkowników.

W poprzednim przykładzie początkowa karta aplikacji zawierała przycisk. Kiedykolwiek użytkownik klika przycisk, zdarzenia interakcji CARD_CLICKED. wyzwala funkcję updateAppHome odświeżającą kartę strony głównej aplikacji, jak pokazano w tym kodzie:

Node.js

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

Python

python/app-home/main.py
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
// 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

Ten przykładowy kod karty wysyła wiadomość przez zwrócenie card JSON. Możesz też użyć usługi Usługa karty Apps Script.

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

Otwórz okna

Aplikacja Google Chat może też reagować na interakcje w ekranie głównym aplikacji, otwierając dialogi.

Okno z różnymi różnymi widżetami.
Rysunek 3. Okno z prośbą o dodanie kontaktu.

Aby otworzyć okno ze strony głównej aplikacji, przetwórz powiązane zdarzenie interakcji według zwracanie funkcji renderActions z nawigacją updateCard, która zawiera Card obiektu. W tym przykładzie aplikacja Google Chat reaguje na kliknięcie przycisku na karcie głównej aplikacji, przetwarzając zdarzenie interakcji CARD_CLICKED i otwierając okno dialogowe:

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

Aby zamknąć okno, przetwórz te zdarzenia interakcji:

  • CLOSE_DIALOG: zamyka okno i wraca do Pierwsza karta główna aplikacji Google Chat.
  • CLOSE_DIALOG_AND_EXECUTE: zamyka okno i odświeża stronę główną aplikacji

W tym przykładowym kodzie do zamykania okna dialogowego i powrotu do karty głównej aplikacji służy metoda CLOSE_DIALOG:

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

Aby zbierać informacje od użytkowników, możesz też tworzyć dialogi sekwencyjne. Do dowiedz się, jak tworzyć sekwencyjne okna dialogowe, zobacz Otwieranie okien i odpowiadanie na nie