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 mit aktivierten interaktiven Funktionen. 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. Folgen Sie dieser Kurzanleitung, um eine interaktive Chat-App in Apps Script zu erstellen.

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. Gehen Sie in der Google Cloud Console zu Menü > Weitere Produkte > Google Workspace > Produktbibliothek > Google Chat API.

    Zur 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 1:1-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 die Startseite der App öffnet, muss die Chat-App das Interaktionsereignis APP_HOME verarbeiten. Dazu wird eine Instanz von RenderActions mit pushCard-Navigation und Card zurückgegeben. Die Karte kann interaktive Widgets wie Schaltflächen oder Texteingaben enthalten, die die Chat-App verarbeiten und mit zusätzlichen Karten oder einem Dialogfeld beantworten kann.

Im folgenden Beispiel zeigt die Chat-App eine erste Startkarten-Ansicht der App mit dem Erstellungszeitpunkt der Karte und einer Schaltfläche an. Wenn ein Nutzer auf die Schaltfläche klickt, gibt die Chat-App eine aktualisierte Karte mit dem Zeitpunkt zurück, zu dem die aktualisierte 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 onAppHome-Funktion, 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 auf der App-Startseite reagieren

Wenn die ursprüngliche Karte der App-Startseite interaktive Widgets wie Schaltflächen oder Auswahleingaben enthält, muss die Chat-App die zugehörigen Interaktionsereignisse verarbeiten. Dazu wird eine Instanz von RenderActions mit der updateCard-Navigation zurückgegeben. Weitere Informationen zum Umgang mit interaktiven Widgets finden Sie unter Von Nutzern eingegebene Informationen verarbeiten.

Im vorherigen Beispiel enthielt die ursprüngliche Karte der App-Startseite 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 Karten-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 im App-Startbildschirm reagieren, indem Dialogfelder geöffnet werden.

Ein Dialogfeld mit verschiedenen Widgets.
Abbildung 3: Dialogfeld, in dem der Nutzer zum Hinzufügen eines Kontakts aufgefordert wird.

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 Startseite der App, indem das Interaktionsereignis CARD_CLICKED verarbeitet und ein Dialogfeld geöffnet wird:

{ 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, verarbeiten Sie die folgenden Interaktionsereignisse:

  • CLOSE_DIALOG: Schließt das Dialogfeld und kehrt zur ursprünglichen Startseite 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 beantworten.