Startseite für eine Google Chat-App erstellen

Auf dieser Seite wird beschrieben, wie Sie mit Ihrer Google Chat-App eine Startseite für Direktnachrichten erstellen. Eine Startseite, in der Google Chat API als App-Startseite bezeichnet, ist eine anpassbare Kartenoberfläche, die auf dem Tab Startseite von Direktnachrichtenbereichen zwischen einem Nutzer und einer Chat-App angezeigt wird.

Startseite einer App mit zwei Widgets
Abbildung 1: Beispiel für eine Startseite, die in Direktnachrichten mit einer Chat-App angezeigt wird

Sie können auf der Startseite der App Tipps zur Interaktion mit der Chat-App teilen oder Nutzern erlauben, über Google Chat auf einen externen Dienst oder ein externes Tool zuzugreifen und es zu verwenden.

Mit dem Card Builder können Sie Nachrichten und Benutzeroberflächen für Chat-Apps entwerfen und in der Vorschau ansehen:

Karten-Tool öffnen

Vorbereitung

Node.js

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Python

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Java

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Apps Script

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App in Apps Script erstellen möchten, folgen Sie dieser Kurzanleitung.

Startseite der App für Ihre Chat-App konfigurieren

Wenn Sie den App-Startbildschirm unterstützen möchten, müssen Sie Ihre Chat-App so konfigurieren, dass sie APP_HOME-Interaktionsereignisse empfängt. Ihre Chat-App empfängt dieses Ereignis, wenn ein Nutzer in einer Direktnachricht in der Chat-App auf den Tab Start klickt.

So aktualisieren Sie Ihre Konfigurationseinstellungen in der Google Cloud Console:

  1. Klicken Sie in der Google Cloud Console auf das Dreistrich-Menü > Weitere Produkte > Google Workspace > Produktbibliothek > Google Chat API.

    Google Chat API

  2. Klicken Sie auf Verwalten und dann auf den Tab Konfiguration.

  3. Gehen Sie unter Interaktive Funktionen zum Abschnitt Funktionen, um die App-Startseite zu konfigurieren:

    1. Klicken Sie das Kästchen Einzelne Nachrichten empfangen an.
    2. Klicken Sie das Kästchen Support App Home an.

  4. Wenn Ihre Chat-App einen HTTP-Dienst verwendet, rufen Sie die Verbindungseinstellungen auf und geben Sie einen Endpunkt für das Feld App-Start-URL an. Sie können dieselbe URL verwenden, die Sie im Feld HTTP-Endpunkt-URL angegeben haben.

  5. Klicken Sie auf Speichern.

Startseite einer App erstellen

Wenn ein Nutzer den App-Startbildschirm öffnet, muss Ihre Chat-App das APP_HOME-Interaktionsereignis verarbeiten, indem eine Instanz von RenderActions mit pushCard-Navigation und Card zurückgegeben wird. Für eine interaktive Nutzung können die Karten interaktive Widgets wie Schaltflächen oder Textfelder enthalten, die die Chat-App verarbeiten und mit zusätzlichen Karten oder einem Dialogfenster beantworten kann.

Im folgenden Beispiel zeigt die Chat-App eine Startkarte mit dem Erstellungszeitpunkt und einer Schaltfläche an. Wenn ein Nutzer auf die Schaltfläche klickt, gibt die Chat-App eine aktualisierte Karte zurück, auf der die Uhrzeit angezeigt wird, zu der die Karte erstellt wurde.

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"))))))))));
}

Apps Script

Implementieren Sie die Funktion onAppHome, die nach allen APP_HOME-Interaktionsereignissen aufgerufen wird:

In diesem Beispiel wird eine Kartennachricht gesendet, indem Karten-JSON zurückgegeben wird. Sie können auch den Kartendienst von Apps Script verwenden.

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

Auf Interaktionen mit der Startseite der App reagieren

Wenn die Startkarte Ihrer App interaktive Widgets wie Schaltflächen oder Auswahleingaben enthält, muss Ihre Chat-App die zugehörigen Interaktionsereignisse verarbeiten, indem sie eine Instanz von RenderActions mit updateCard-Navigation zurückgibt. Weitere Informationen zum Umgang mit interaktiven Widgets finden Sie unter Von Nutzern eingegebene Informationen verarbeiten.

Im vorherigen Beispiel enthielt die erste Startseitenkarte der App eine Schaltfläche. Wenn ein Nutzer auf die Schaltfläche klickt, löst ein CARD_CLICKED-Interaktionsereignis die Funktion updateAppHome aus, um die Startkarte der App zu aktualisieren, wie im folgenden Code dargestellt:

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;
}

Apps Script

In diesem Beispiel wird eine Kartennachricht gesendet, indem card JSON zurückgegeben wird. Sie können auch den Kartendienst von Apps Script verwenden.

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

Dialogfelder öffnen

Ihre Chat-App kann auch auf Interaktionen auf dem Startbildschirm der App reagieren, indem Dialogfelder geöffnet werden.

Ein Dialogfeld mit verschiedenen Widgets.
Abbildung 3: Ein Dialogfeld, in dem ein Nutzer aufgefordert wird, einen Kontakt hinzuzufügen.

Wenn Sie ein Dialogfeld über die Startseite der App öffnen möchten, verarbeiten Sie das zugehörige Interaktionsereignis, indem Sie renderActions mit updateCard-Navigation zurückgeben, die ein Card-Objekt enthält. Im folgenden Beispiel reagiert eine Chat-App auf einen Klick auf eine Schaltfläche auf der Startkarte einer App, indem sie das Interaktionsereignis CARD_CLICKED verarbeitet und ein Dialogfeld öffnet:

{ 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" }}
  }]}}]
}]}}]}}}

Um ein Dialogfeld zu schließen, müssen Sie die folgenden Interaktionsereignisse verarbeiten:

  • CLOSE_DIALOG: Schließt das Dialogfeld und kehrt zur Startkarte der Chat-App zurück.
  • CLOSE_DIALOG_AND_EXECUTE: Schließt das Dialogfeld und aktualisiert die Startkarte der App.

Im folgenden Codebeispiel wird CLOSE_DIALOG verwendet, um ein Dialogfeld zu schließen und zur Startkarte der App zurückzukehren:

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

Sie können auch sequenzielle Dialoge erstellen, um Informationen von Nutzern zu erfassen. Informationen zum Erstellen von sequenziellen Dialogen finden Sie unter Dialoge öffnen und darauf reagieren.