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 Kartenoberfläche, die im Tab Startseite von Direktnachrichtenbereichen 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.

Sie können die App-Startseite verwenden, um Tipps zur Interaktion mit der Chat-App zu geben oder Nutzern den Zugriff auf und die Verwendung eines externen Dienstes oder Tools über Chat zu 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, führen Sie diese Kurzanleitung aus.

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, führen Sie diese Kurzanleitung aus.

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, führen Sie diese Kurzanleitung aus.

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, führen Sie diese Kurzanleitung aus.

App-Startseite für Ihre Chat-App konfigurieren

Wenn Sie die App-Startseite 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 immer dann, wenn ein Nutzer in einer Direktnachricht mit der Chat-App auf den Tab Startseite klickt.

So aktualisieren Sie die Konfigurationseinstellungen in der Google Cloud Console:

Klicken Sie in der Google Cloud Console auf das Menü > APIs und Dienste > Aktivierte APIs und Dienste > Google Chat API > Konfiguration. Zur Chat API-Konfiguration
Gehen Sie unter Interaktive Funktionen zum Bereich Funktionsweise und wählen Sie App-Startseite unterstützen aus.
Wenn Ihre Chat-App einen HTTP-Dienst verwendet, gehen Sie zu Verbindungseinstellungen und geben Sie einen Endpunkt für das App-Startseiten-URL Feld an. Sie können dieselbe URL verwenden, die Sie im HTTP-Endpunkt-URL Feld angegeben haben.
Klicken Sie auf Speichern.

Karte für die App-Startseite erstellen

Wenn ein Nutzer die App-Startseite öffnet, muss Ihre Chat-App das APP_HOME Interaktionsereignis verarbeiten, indem sie eine Instanz von RenderActions mit pushCard Navigation und einer 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 sie mit zusätzlichen Karten oder einem Dialogfeld reagieren kann.

Im folgenden Beispiel zeigt die Chat-App eine erste Karte für die App-Startseite mit der Uhrzeit, zu der die Karte erstellt wurde, und einer Schaltfläche an. Wenn ein Nutzer auf die Schaltfläche klickt, gibt die Chat-App eine aktualisierte Karte mit der Uhrzeit zurück, zu der die aktualisierte Karte erstellt wurde.

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 Kartennachricht 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 Interaktionen auf der App-Startseite reagieren

Wenn Ihre erste Karte für die App-Startseite 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 Karte für die 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 Karte für die App-Startseite zu aktualisieren, wie im folgenden Code gezeigt:

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 Kartennachricht 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 der App-Startseite 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 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 Karte für die App-Startseite, 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 das Dialogfeld und kehrt zur ersten Karte für die App-Startseite der Chat-App zurück.
CLOSE_DIALOG_AND_EXECUTE: Schließt das Dialogfeld und aktualisiert die Karte für die App-Startseite.

Im folgenden Codebeispiel wird CLOSE_DIALOG verwendet, um ein Dialogfeld zu schließen und zur Karte für die App-Startseite zurückzukehren:

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

Wenn Sie Informationen von Nutzern erfassen möchten, können Sie auch sequenzielle Dialogfelder erstellen. Informationen zum Erstellen sequenzieller Dialogfelder finden Sie unter Dialogfelder öffnen und darauf reagieren.

Beispiele für Chat-Apps, die die App-Startseite verwenden
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

App-Startseite für Ihre Chat-App konfigurieren

Karte für die App-Startseite erstellen

Node.js

Python

Java

Apps Script

Auf Interaktionen auf der App-Startseite reagieren

Node.js

Python

Java

Apps Script

Dialogfelder öffnen

Weitere Informationen

Startseite für eine Google Chat-App erstellen