Startseite für eine Google Chat-App erstellen

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

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

Auf der Startseite der App können Sie Tipps für die Interaktion mit der Chat-App geben oder Nutzern ermöglichen, über Chat auf einen externen Dienst oder ein externes Tool zuzugreifen und diesen zu verwenden.

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

Card Builder öffnen

Vorbereitung

Node.js

Eine Google Chat-App, die Interaktionsereignisse empfängt und darauf reagiert. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Python

Eine Google Chat-App, die Interaktionsereignisse empfängt und darauf reagiert. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Java

Eine Google Chat-App, die Interaktionsereignisse empfängt und darauf reagiert. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Apps Script

Eine Google Chat-App, die Interaktionsereignisse empfängt und darauf reagiert. Wenn Sie eine interaktive Chat-App in Apps Script erstellen möchten, folgen Sie dieser Kurzanleitung.

App-Startseite für Ihre Chat-App konfigurieren

Damit die Startseite der App unterstützt wird, müssen Sie Ihre Chat-App so konfigurieren, dass sie APP_HOME-Interaktionsereignisse empfängt. Ihre Chat-App empfängt dieses Ereignis immer dann, wenn ein Nutzer in einer Direktnachricht mit der Chat-App auf den Tab Startseite klickt.

So aktualisieren Sie Ihre Konfigurationseinstellungen in der Google Cloud Console:

  1. Gehen Sie in der Google Cloud Console zum 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. Rufen Sie unter Interaktive Funktionen den Bereich Funktionsweise auf und wählen Sie App-Startseite unterstützen aus.

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

  5. Klicken Sie auf Speichern.

Karte für die App-Startseite erstellen

Wenn ein Nutzer die App-Startseite öffnet, muss Ihre Chat-App das Interaktionsereignis APP_HOME verarbeiten, indem sie eine Instanz von RenderActions mit pushCard-Navigation und einem Card zurückgibt. Um eine interaktive Umgebung zu schaffen, kann die Karte interaktive Widgets wie Schaltflächen oder Texteingaben enthalten, die von der Chat-App verarbeitet werden können und auf die mit zusätzlichen Karten oder einem Dialog geantwortet werden kann.

Im folgenden Beispiel wird in der Chat-App eine erste Karte auf der App-Startseite angezeigt, auf der die Uhrzeit der Erstellung der Karte und eine Schaltfläche zu sehen sind. Wenn ein Nutzer auf die Schaltfläche klickt, gibt die Chat App eine aktualisierte Karte zurück, auf der die Uhrzeit der Erstellung der aktualisierten Karte angezeigt wird.

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 Kartenmitteilung gesendet, indem Karten-JSON zurückgegeben wird. Sie können auch den Apps Script-Kartendienst 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 App-Startseiteninteraktionen reagieren

Wenn Ihre erste App-Startseite interaktive Widgets wie Schaltflächen oder Auswahlfelder 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 ursprüngliche App-Startseitenkarte eine Schaltfläche. Immer wenn ein Nutzer auf die Schaltfläche klickt, wird durch ein CARD_CLICKED-Interaktionsereignis die Funktion updateAppHome ausgelöst, um die App-Startseite zu aktualisieren. Das ist im folgenden Code zu sehen:

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 Kartenmitteilung gesendet, indem Karten-JSON zurückgegeben wird. Sie können auch den Apps Script-Kartendienst 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 App-Startbildschirm reagieren, indem sie Dialogfelder öffnet.

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 App-Startseite öffnen möchten, verarbeiten Sie das zugehörige Interaktionsereignis, indem Sie renderActions mit der 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 einer App-Startseite-Karte, indem sie das CARD_CLICKED-Interaktionsereignis 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" }}
  }]}}]
}]}}]}}}

So schließen Sie ein Dialogfeld:

  • CLOSE_DIALOG: Schließt den Dialog und kehrt zur ursprünglichen App-Startseite der Chat-App zurück.
  • CLOSE_DIALOG_AND_EXECUTE: Schließt das Dialogfeld und aktualisiert die App-Startseite.

Im folgenden Codebeispiel wird CLOSE_DIALOG verwendet, um ein Dialogfeld zu schließen und zur Startseite 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 sequenzieller Dialoge finden Sie unter Dialoge öffnen und darauf reagieren.