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 możliwością dostosowania, która pojawia się na karcie Strona główna w pokojach 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, która pojawia się w wiadomościach bezpośrednich z aplikacją Google Chat.

Na stronie głównej aplikacji możesz udostępniać wskazówki dotyczące interakcji z aplikacją Chat lub umożliwiać użytkownikom dostęp do usługi lub narzędzia zewnętrznego i korzystanie z nich w Chat.

Użyj narzędzia do tworzenia kart, aby projektować i wyświetlać podgląd wiadomości oraz interfejsów użytkownika aplikacji w Google Chat:

Otwórz narzędzie do tworzenia kart

Wymagania wstępne

Node.js

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do czatu za pomocą usługi HTTP, zapoznaj się z tym krótkim wprowadzeniem.

Python

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do czatu za pomocą usługi HTTP, zapoznaj się z tym krótkim wprowadzeniem.

Java

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do czatu za pomocą usługi HTTP, zapoznaj się z tym krótkim wprowadzeniem.

Google Apps Script

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do obsługi czatu w Apps Script, wykonaj czynności opisane w tym krótkim wprowadzeniu.

Konfigurowanie strony głównej aplikacji w Google Chat

Aby obsługiwać stronę główną aplikacji, musisz skonfigurować aplikację do obsługi czatu tak, aby odbierała APP_HOMEzdarzenia interakcji. Aplikacja do obsługi czatu otrzymuje to zdarzenie za każdym razem, gdy użytkownik kliknie kartę Strona główna w wiadomości na czacie z aplikacją.

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

  1. W konsoli Google Cloud otwórz Menu > Wyświetl wszystkie usługi > Inne usługi Google > Google Workspace > Biblioteka usług > Google Chat API.

    Otwórz Google Chat API

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

  3. W sekcji Funkcje interaktywne otwórz sekcję Funkcje i kliknij Strona główna aplikacji pomocy.

  4. Jeśli 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 Adres URL punktu końcowego HTTP.

  5. Kliknij Zapisz.

Tworzenie karty ekranu głównego aplikacji

Gdy użytkownik otworzy stronę główną aplikacji do obsługi czatu, aplikacja musi obsłużyć zdarzenie interakcji APP_HOME, zwracając instancję RenderActions z nawigacją pushCard i Card. Aby utworzyć interaktywny element, karta może zawierać interaktywne widżety, takie jak przyciski lub pola tekstowe, które aplikacja do obsługi czatu może przetwarzać i na które może odpowiadać za pomocą dodatkowych kart lub okna dialogowego.

W poniższym przykładzie aplikacja Chat wyświetla początkową kartę strony głównej aplikacji, która zawiera godzinę utworzenia karty i przycisk. Gdy użytkownik kliknie przycisk, aplikacja Chat zwróci zaktualizowaną kartę, na której będzie widoczny czas utworzenia zaktualizowanej karty.

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ł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
/**
 * 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"
      }}
    }]}}
  ]}]};
}

Reagowanie na interakcje na stronie głównej aplikacji

Jeśli początkowa karta główna aplikacji zawiera interaktywne widżety, takie jak przyciski lub pola wyboru, aplikacja do obsługi czatu musi obsługiwać powiązane zdarzenia interakcji, zwracając instancję RenderActions z nawigacją updateCard. Więcej informacji o obsłudze interaktywnych widżetów znajdziesz w artykule Przetwarzanie informacji wprowadzanych przez użytkowników.

W poprzednim przykładzie początkowa karta strony głównej aplikacji zawierała przycisk. Za każdym razem, gdy użytkownik kliknie przycisk, CARD_CLICKED zdarzenie interakcji 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ł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
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

Otwieranie okien

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

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

Aby otworzyć okno z poziomu strony głównej aplikacji, przetwórz powiązane zdarzenie interakcji, zwracając renderActions z nawigacją updateCard, która zawiera obiekt Card. W tym przykładzie aplikacja Google Chat odpowiada na kliknięcie przycisku na karcie Strona główna 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 początkowej karty aplikacji w Google Chat.
  • CLOSE_DIALOG_AND_EXECUTE: zamyka okno i odświeża kartę główną aplikacji.

W tym przykładzie kodu używamy metody CLOSE_DIALOG, aby zamknąć okno i wrócić do karty głównej aplikacji:

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

Aby zbierać informacje od użytkowników, możesz też tworzyć sekwencyjne okna dialogowe. Aby dowiedzieć się, jak tworzyć sekwencyjne okna, przeczytaj artykuł Otwieranie okien i odpowiadanie na nie.