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, die in der Google Chat API als App-Startseite bezeichnet wird, 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 den Zugriff auf und die Verwendung eines externen Dienstes oder Tools über Chat ermöglichen.

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.

Startseite der App für Ihre Chat-App konfigurieren

Damit die App-Startseite 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:

Rufen Sie in der Google Cloud Console das Menü > Alle Produkte ansehen > Andere Google-Produkte > Google Workspace > Produktbibliothek > Google Chat API auf.

Zur Google Chat API
Klicken Sie auf Verwalten und dann auf den Tab Konfiguration.
Rufen Sie unter Interaktive Funktionen den Bereich Funktionsweise auf und wählen Sie App-Startseite unterstützen aus.
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.
Klicken Sie auf Speichern.

Startseitenkarte für die App 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 interaktive Inhalte zu erstellen, 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 App-Startseitenkarte mit der Uhrzeit, zu der die Karte erstellt wurde, und einer Schaltfläche angezeigt. 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

Auf GitHub ansehen

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

Auf GitHub ansehen

@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

Auf GitHub ansehen

// 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

Auf GitHub ansehen

/**
 * 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 ursprüngliche 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 erste 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 wird im folgenden Code veranschaulicht:

Node.js

node/app-home/index.js

Auf GitHub ansehen

// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py

Auf GitHub ansehen

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

Auf GitHub ansehen

// 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

Auf GitHub ansehen

/**
 * 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**: 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 Schaltflächenklick 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" }}
  }]}}]
}]}}]}}}

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

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 einen Dialog 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.

Beispiele für Chat-Apps ansehen, in denen die App-Startseite verwendet wird
Dialogfelder öffnen und darauf reagieren

Startseite für eine Google Chat-App erstellen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Vorbereitung

Node.js

Python

Java

Apps Script

Startseite der App für Ihre Chat-App konfigurieren

Startseitenkarte für die App erstellen

Node.js

Python

Java

Apps Script

Auf App-Startseiteninteraktionen reagieren

Node.js

Python

Java

Apps Script

Dialogfelder öffnen

Weitere Informationen

Startseite für eine Google Chat-App erstellen