Informationen von Google Chat-Nutzern erheben und verarbeiten

In diesem Leitfaden wird beschrieben, wie Google Chat-Apps Informationen von Nutzern erheben und verarbeiten können, indem sie Formulareingaben in cardbasierten Benutzeroberflächen einbinden.

In Google Chat werden Add-ons für Nutzer als Google Chat-Apps angezeigt. Weitere Informationen finden Sie unter Google Chat erweitern – Übersicht.

Chat-Apps fordern Nutzer auf, Informationen anzugeben, um Aktionen in oder außerhalb von Google Chat auszuführen. Das kann beispielsweise so geschehen:

• Konfigurieren Sie die Einstellungen. So können Sie beispielsweise Nutzern erlauben, Benachrichtigungseinstellungen anzupassen oder die Chat-App für einen oder mehrere Gruppenbereiche zu konfigurieren und hinzuzufügen.
• Informationen in anderen Google Workspace-Anwendungen erstellen oder aktualisieren Sie können Nutzern beispielsweise erlauben, einen Google Kalender-Termin zu erstellen.
• Nutzern erlauben, auf Ressourcen in anderen Apps oder Webdiensten zuzugreifen und sie zu aktualisieren So können Nutzer beispielsweise mit einer Chat-App den Status eines Supporttickets direkt über einen Chatbereich aktualisieren.

Vorbereitung

Formulare mit Karten erstellen

Zum Erfassen von Informationen entwerfen Chat-Apps Formulare und deren Eingaben und bauen sie in Karten ein. Chat-Apps können die folgenden Chat-Oberflächen verwenden, um Nutzern Karten anzuzeigen:

• Chatnachrichten, die eine oder mehrere Karten enthalten.
• Dialogfelder: Karten, die in Nachrichten und auf Startseiten in einem neuen Fenster geöffnet werden.

In Chat-Apps können die Karten mit den folgenden Widgets erstellt werden:

• Formular-Eingabe-Widgets, die Informationen von Nutzern anfordern. Optional können Sie Validierungsregeln für Formular-Eingabe-Widgets hinzufügen, damit Nutzer Informationen korrekt eingeben und formatieren. In Chat-Apps können die folgenden Eingabe-Widgets für Formulare verwendet werden:

  • Texteingaben (textInput) für freien Text oder Vorschläge.
  • Auswahleingaben (selectionInput) sind auswählbare UI-Elemente wie Kästchen, Optionsfelder und Drop-down-Menüs. Auswahl-Eingabe-Widgets können auch Elemente aus statischen oder dynamischen Datenquellen einfügen. Nutzer können beispielsweise eine Liste der Chatbereiche auswählen, in denen sie Mitglied sind.
  • Datumsauswahl (dateTimePicker) für Datums- und Uhrzeitangaben.

• Ein Schaltflächen-Widget, mit dem Nutzer Werte einreichen können, die sie auf der Karte eingegeben haben. Nachdem ein Nutzer auf die Schaltfläche geklickt hat, kann die Chat-App die empfangenen Informationen verarbeiten.

Im folgenden Beispiel werden auf einer Karte Kontaktdaten mithilfe einer Texteingabe, einer Datumsauswahl und einer Auswahleingabe erfasst:

Weitere Beispiele für interaktive Widgets, mit denen Sie Informationen erfassen können, finden Sie in der Google Chat API-Dokumentation unter Interaktive Karte oder Dialogfeld entwerfen.

Daten von interaktiven Widgets empfangen

Jedes Mal, wenn Nutzer auf eine Schaltfläche klicken, wird die Aktion der Chat-App mit Informationen zur Interaktion ausgelöst. Im commonEventObject der Ereignisnutzlast enthält das formInputs-Objekt alle Werte, die der Nutzer eingibt.

Sie können die Werte aus dem Objekt commonEventObject.formInputs.WIDGET_NAME abrufen. Dabei ist WIDGET_NAME das name-Feld, das Sie für das Widget angegeben haben. Die Werte werden als bestimmter Datentyp für das Widget zurückgegeben.

Im Folgenden sehen Sie einen Teil eines Ereignisobjekts, in dem ein Nutzer Werte für jedes Widget eingegeben hat:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Um die Daten zu empfangen, verarbeitet Ihre Chat-App das Ereignisobjekt, um die Werte abzurufen, die Nutzer in Widgets eingeben. In der folgenden Tabelle wird gezeigt, wie Sie den Wert für ein bestimmtes Formulareingabe-Widget abrufen. Für jedes Widget wird in der Tabelle der Datentyp angezeigt, den das Widget akzeptiert, wo der Wert im Ereignisobjekt gespeichert wird, und ein Beispielwert.

Daten auf eine andere Karte übertragen

Nachdem ein Nutzer Informationen von einer Karte gesendet hat, müssen Sie möglicherweise zusätzliche Karten zurücksenden, um eine der folgenden Aktionen auszuführen:

• Erstellen Sie separate Abschnitte, um Nutzern das Ausfüllen längerer Formulare zu erleichtern.
• Bieten Sie Nutzern die Möglichkeit, sich eine Vorschau der Informationen auf der ersten Karte anzusehen und zu bestätigen, damit sie ihre Antworten vor dem Senden prüfen können.
• Die restlichen Teile des Formulars werden dynamisch ausgefüllt. Wenn Nutzer beispielsweise aufgefordert werden sollen, einen Termin zu erstellen, könnte eine Chat-App eine erste Karte mit der Frage nach dem Grund für den Termin anzeigen und dann eine weitere Karte mit verfügbaren Zeiten basierend auf dem Termintyp einblenden.

Um die Dateneingabe von der ursprünglichen Karte zu übertragen, können Sie das button-Widget mit actionParameters erstellen, das die name des Widgets und den vom Nutzer eingegebenen Wert enthält, wie im folgenden Beispiel gezeigt:

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Dabei ist WIDGET_NAME die name des Widgets und USER_INPUT_VALUE die Eingabe des Nutzers. Bei einer Texteingabe, über die der Name einer Person erfasst wird, ist der Widget-Name beispielsweise contactName und ein Beispielwert ist Kai O.

Wenn ein Nutzer auf die Schaltfläche klickt, erhält Ihre Chat-App ein Ereignisobjekt, von dem Sie Daten empfangen können.

Auf eine Formulareinreichung reagieren

Nachdem die Chat-App die Daten aus einer Kartennachricht oder einem Kartendialog erhalten hat, antwortet sie entweder mit einer Empfangsbestätigung oder gibt einen Fehler zurück.

Im folgenden Beispiel sendet eine Chat-App eine SMS, um zu bestätigen, dass ein Formular, das über eine Kartennachricht gesendet wurde, erfolgreich empfangen wurde.

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Wenn Sie ein Dialogfeld verarbeiten und schließen möchten, geben Sie ein RenderActions-Objekt zurück, in dem angegeben ist, ob Sie eine Bestätigungsnachricht senden, die ursprüngliche Nachricht oder Karte aktualisieren oder das Dialogfeld einfach schließen möchten. Eine Anleitung finden Sie unter Dialogfeld schließen.

Fehlerbehebung

Wenn eine Google Chat-App oder Karte einen Fehler zurückgibt, wird in der Chat-Benutzeroberfläche die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage konnte nicht verarbeitet werden“ Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder -Karte führt zu einem unerwarteten Ergebnis. Beispielsweise wird möglicherweise keine Kartennachricht angezeigt.

Auch wenn in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, die Ihnen bei der Fehlerbehebung helfen, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Ansehen, Entfernen und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben.