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.

Ein Dialogfeld mit verschiedenen Widgets.
Abbildung 1: Eine Beispiel-Chat-App, die ein Dialogfeld zum Erfassen von Kontaktdaten öffnet.

Chat-Apps fordern von Nutzern Informationen an, um Aktionen in oder außerhalb von Google Chat auszuführen. Das kann auf folgende Arten geschehen:

  • Konfigurieren Sie die Einstellungen. Beispielsweise können Sie Nutzern erlauben, Benachrichtigungseinstellungen anzupassen. oder konfigurieren Sie die Chat-App und fügen Sie sie einer oder mehreren Leerzeichen.
  • 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

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. So erstellen Sie ein Chat-App verwenden, führen Sie eine der folgenden Kurzanleitungen aus für die App-Architektur, die Sie verwenden möchten:

Formulare mit Karten erstellen

Um Daten zu erheben, werden von Chat-Apps Formulare und deren Eingaben erstellt. und sie in Karten verpacken. Um Nutzern Karten anzuzeigen, Chat-Apps können die folgenden Chat-Oberflächen verwenden:

  • Nachrichten, die eine oder mehrere Karten enthalten.
  • Startseiten Dabei handelt es sich um eine Karte, die direkt auf dem Tab Startseite mit der Chat App.
  • Dialogfelder: Karten, die sich öffnen Nachrichten und Startseiten in einem neuen Fenster öffnen.

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

  • Formulareingabe-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 verwendet werden:

    • Textfelder (textInput) für freien oder vorgeschlagenen Text.
    • Auswahleingaben (selectionInput) sind auswählbare UI-Elemente wie Kästchen, Optionsfeldern und Dropdown-Menüs. Widgets zur Auswahleingabe können auch Elemente aus statischen oder dynamischen Datenquellen auszufüllen. Nutzer können beispielsweise aus einer Liste der Chatbereiche auswählen, in denen sie Mitglied sind.
    • Datum/Uhrzeit-Auswahl (dateTimePicker) für Datums- und Uhrzeiteinträge.

  • Ein Schaltflächen-Widget damit Nutzer Werte auf der Karte einreichen können. Nachdem ein Nutzer auf die Schaltfläche geklickt hat, empfangene Informationen verarbeiten.

Im Folgenden sehen Sie eine Karte mit drei verschiedenen Arten von Datums- und Zeiteingaben:

Weitere Beispiele für interaktive Widgets zum Erfassen finden Sie unter Entwerfen Sie eine interaktive Karte oder ein interaktives Dialogfeld.

Daten von interaktiven Widgets empfangen

Wenn Nutzer auf eine Schaltfläche klicken, erhalten Chat-Apps ein CARD_CLICKED-Interaktionsereignis mit Informationen zur Interaktion. Die Nutzlast von CARD_CLICKED-Interaktionsereignisse enthalten einen common.formInputs. -Objekt mit allen Werten, die der Nutzer eingibt.

Sie können die Werte aus dem Objekt common.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 (als Inputs-Objekt dargestellt). Im folgenden Beispiel werden auf einer Karte Kontaktdaten mithilfe einer Texteingabe, einer Datumsauswahl und eines Auswahleingabe-Widgets erfasst:

{
  "textInput": {
    "name": "contactName",
    "label": "First and last name",
    "type": "SINGLE_LINE"
  }
}, {
  "dateTimePicker": {
    "name": "contactBirthdate",
    "label": "Birthdate",
    "type": "DATE_ONLY"
  }
}, {
  "selectionInput": {
    "name": "contactType",
    "label": "Contact type",
    "type": "RADIO_BUTTON",
    "items": [
      {
        "text": "Work",
        "value": "Work",
        "selected": false
      },
      {
        "text": "Personal",
        "value": "Personal",
        "selected": false
      }
    ]
  }
}

Interaktionsereignis verarbeiten

Wenn ein Nutzer Daten in eine Karte oder ein Dialogfeld eingibt, erhält Ihre Chat-App ein Interaktionsereignis vom Typ CARD_CLICKED, das die vom Nutzer eingegebenen Werte enthält.

Hier sehen Sie einen Teil eines CARD_CLICKED-Interaktionsereignisses, ein Nutzer Werte für jedes Widget eingegeben hat:

HTTP

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

Apps Script 

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

Damit die Daten empfangen werden können, verarbeitet Ihre Chat-App das Interaktionsereignis, um die Werte zu erhalten, 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 Interaktionsereignis gespeichert wird, und ein Beispielwert.

Widget für die Formulareingabe Datentyp der Eingabe Eingabewert aus dem Interaktionsereignis Beispielwert
textInput stringInputs events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Um den ersten oder einzigen Wert zu erhalten, events.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker, in dem nur Datumsangaben zulässig sind. dateInput events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

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.
  • Füllen Sie die verbleibenden Teile des Formulars dynamisch. Wenn Sie Nutzer beispielsweise zum Erstellen eines Termins auffordern möchten, 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 ersten Karte zu übertragen, kannst du die button erstellen. Widget mit actionParameters die den name des Widgets und den Wert enthalten, den der Nutzer eingibt, wie hier im folgenden Beispiel:

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

Dabei ist WIDGET_NAME die name des Widgets und der Wert USER_INPUT_VALUE ist das, was der Nutzer eingibt. Für einen Text die den Namen einer Person erfasst, lautet der Name des Widgets contactName und ein Beispielwert ist Kai O.

Wenn ein Nutzer auf die Schaltfläche klickt, erhält Ihre Chat-App eine CARD_CLICKED Interaktionsereignis. Zum Abrufen der Werte können Sie das event.common.parameters-Objekt verwenden.

Das folgende Beispiel zeigt, wie Sie Parameter übergeben können, Eingabedaten für eine Funktion, die die nächste Karte öffnet:

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

Apps Script 

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

Auf gesendete Formulare antworten

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 sie ein Formular erhalten hat, das von einem Kartennachricht.

Apps Script 

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

Um ein Dialogfeld zu verarbeiten und zu schließen, wird ein ActionResponse das angibt, ob Sie eine Bestätigungsnachricht senden, Originalnachricht oder -karte oder schließen Sie einfach das Dialogfeld. Eine Anleitung dazu 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 kann die Chat-UI Es wird zwar keine Fehlermeldung angezeigt, aber die Chat-App oder die Karte zu einem unerwarteten Ergebnis führt. z. B. wird eine Kartennachricht angezeigt werden.

Auch wenn in der Chat-Benutzeroberfläche möglicherweise keine Fehlermeldung angezeigt wird, beschreibende Fehlermeldungen und Protokolldaten stehen zur Fehlerbehebung zur Verfügung. wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Ansehen, Entfernen und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben.