Startseite für eine Google Chat-App erstellen

Auf dieser Seite erfahren Sie, wie Sie eine Startseite für Direktnachrichten mit Ihrem Google Chat App. Eine Startseite, die im Google Ads-System als App-Startseite bezeichnet wird Die Google Chat API ist eine anpassbare Kartenoberfläche auf dem Tab Startseite. von Gruppenbereiche für Direktnachrichten zwischen einem Nutzer und einer Chat-App.

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

Über die Startseite der App kannst du Tipps zur Interaktion mit den Chat-App oder lassen Sie Nutzer auf eine externen Dienst oder Tool von Chat


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, 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. So erstellen Sie ein Chat-App mit einem HTTP-Dienst verwenden können, führen Sie diese Kurzanleitung aus.

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 mit aktivierten interaktiven Funktionen. Wenn Sie eine interaktive Chat-App in Apps Script erstellen möchten, folgen Sie dieser Kurzanleitung.

App-Startseite 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 die Konfigurationseinstellungen in der Google Cloud Console:

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

    Google Chat API

  2. Klicken Sie auf Manage (Verwalten) und dann auf den Tab Configuration (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, gehen Sie zu Verbindungseinstellungen und geben Sie einen Endpunkt für die App Home URL (URL der App-Startseite) ein. 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 APP_HOME-Interaktionsereignis, indem eine Instanz von RenderActions mit pushCard-Navigation und einem Card 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 Dialog beantworten kann.

Im folgenden Beispiel zeigt die Chat-App eine erste Karte auf der App-Startseite, auf der die Erstellungs- und eine Schaltfläche. Wenn ein Nutzer auf die Schaltfläche klickt, gibt eine aktualisierte Karte zurück, die den Erstellungszeitpunkt der aktualisierten Karte anzeigt.

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
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@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() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

Apps Script

Implementieren Sie die onAppHome-Funktion, die nach allen APP_HOME-Elementen aufgerufen wird. Interaktionsereignisse:

In diesem Beispiel wird eine Kartennachricht gesendet, JSON-Karte Sie können auch die Apps Script-Kartendienst

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 enthält, z. B. Schaltflächen oder Auswahleingaben muss Ihre Chat-App der zugehörigen Interaktionsereignisse, indem eine Instanz von RenderActions mit updateCard-Navigation. 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, JSON-Karte Sie können auch die Apps Script-Kartendienst

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 reagieren auf dem Startbildschirm der App, indem Sie Dialogfelder öffnen.

Ein Dialogfeld mit einer Vielzahl verschiedener 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 antwortet eine Chat-App auf einen Schaltflächenklick von einer App-Startseitenkarte durch Verarbeitung der CARD_CLICKED Interaktionsereignis und das Öffnen eines Dialogfelds:

{ 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 Startkarte der Chat-App zurück.
  • CLOSE_DIALOG_AND_EXECUTE: Schließt das Dialogfeld und aktualisiert den Startbildschirm der App .

Im folgenden Codebeispiel wird CLOSE_DIALOG verwendet, um ein Dialogfeld zu schließen und zur Karte auf der Startseite der App:

{ 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.