Tworzenie strony głównej aplikacji Google Chat

Na tej stronie znajdziesz instrukcje tworzenia strony głównej dla wiadomości bezpośrednich w aplikacji Google Chat. Strona główna, zwana w interfejsie Google Chat API stroną główną aplikacji, to konfigurowalny interfejs kart, 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
Ilustracja 1. Przykład strony głównej wyświetlanej w wiadomościach bezpośrednich 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.

Korzystając z Kreatora kart, możesz projektować i przeglądać interfejsy użytkownika oraz wiadomości w aplikacji Google Chat:

Otwórz kreatora kart

Wymagania wstępne

Node.js

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Python

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Java

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Google Apps Script

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat w Apps Script, wykonaj krótkie wprowadzenie.

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 stronę 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 Strona główna aplikacji pomocy.

  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.

Tworzenie karty głównej aplikacji

Gdy użytkownik otworzy stronę główną aplikacji, aplikacja Google Chat musi obsłużyć zdarzenie interakcji APP_HOME, zwracając instancję RenderActions z nawigacją pushCard i elementem 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 tym przykładzie aplikacja Google Chat wyświetla kartę początkową z czasem utworzenia karty oraz przyciskiem. 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
@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

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 karty w 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"
      }}
    }]}}
  ]}]};
}

Odpowiadanie na interakcje na stronie głównej 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. Gdy użytkownik kliknie przycisk, zdarzenie interakcji CARD_CLICKED uruchamia funkcję updateAppHome, która odświeża kartę główną 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

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.

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 widżetami.
Ilustracja 3. Okno z prośbą o dodanie kontaktu.

Aby otworzyć okno na stronie głównej aplikacji, przetwórz powiązane zdarzenie interakcji, zwracając renderActions z navigacją updateCard zawierającą obiekt Card. 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 zwraca do początkowej karty głównej aplikacji Google Chat.
  • CLOSE_DIALOG_AND_EXECUTE: zamyka okno i odświeża kartę 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. Aby dowiedzieć się, jak tworzyć dialogi sekwencyjne, przeczytaj artykuł Otwieranie dialogów i odpowiadanie na nie.