Informationen von Google Chat-Nutzern erheben und verarbeiten

In diesem Leitfaden wird beschrieben, wie Google Chat-Apps Daten erheben und verarbeiten können indem Sie Formulareingaben in kartenbasierten Oberflächen erstellen.

Ein Dialogfeld mit einer Vielzahl verschiedener 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 diese 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

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

  • Nachrichten die eine oder mehrere Karten enthalten.
  • Startseiten: Eine Karte, die auf dem Tab Startseite in Direktnachrichten in der Chat App angezeigt wird.
  • 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:

  • Formular-Eingabe-Widgets, die Informationen von Nutzern anfordern. Optional können Sie Validierung hinzufügen Eingabe-Widgets zu bilden, um sicherzustellen, dass Nutzer Informationen eingeben und formatieren korrekt sind. Chat-Apps können die folgenden Formulareingabe-Widgets verwenden:

    • Texteingaben (textInput) für Freitext oder Textvorschläge.
    • 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, 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 sehen Sie eine Karte mit drei verschiedenen Arten von Datums- und Zeiteingaben:

Weitere Beispiele für interaktive Widgets, mit denen Sie Informationen erfassen können, finden Sie unter Interaktive Karte oder Dialogfeld entwerfen.

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-Interaktionsereignissen enthält ein common.formInputs-Objekt mit allen Werten, die der Nutzer eingibt.

Sie können die Werte aus dem Objekt abrufen, common.formInputs.WIDGET_NAME, wobei WIDGET_NAME ist das Feld name, das Sie für das Widget angegeben haben. Die Werte werden als spezifischer Datentyp für das Widget zurückgegeben (dargestellt als Ein Inputs-Objekt). Im folgenden Beispiel werden auf einer Karte Kontaktdaten mithilfe einer Eingabe-Widget, Datums-/Uhrzeitauswahl und Auswahleingabe-Widget:

{
  "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
      }
    ]
  }
}

Ereignis vom Typ „Interaction“ verarbeiten

Wenn ein Nutzer Daten in eine Karte oder ein Dialogfeld eingibt, Die Chat-App empfängt eine Chat-App CARD_CLICKED-Interaktionsereignis, 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 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 weitere Karten, mit denen Sie Folgendes tun können:

  • Erstellen Sie separate Abschnitte, um Nutzern das Ausfüllen längerer Formulare zu erleichtern.
  • Bieten Sie Nutzern eine Vorschau und Bestätigung der Informationen auf der ersten Karte, damit sie können ihre Antworten vor dem Einreichen noch einmal prüfen.
  • Die restlichen Teile des Formulars werden dynamisch ausgefüllt. 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 die Methode event.common.parameters -Objekt enthält.

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 ein Formular, das über eine Kartennachricht gesendet wurde, erfolgreich empfangen wurde.

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

Wenn Sie ein Dialogfeld verarbeiten und schließen möchten, geben Sie ein ActionResponse-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 dazu finden Sie unter Dialogfeld schließen

Fehlerbehebung

Wenn eine Google Chat-App oder card gibt einen Fehler zurück. Der Parameter In der Chatoberfläche wird die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage kann 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 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. Hilfe bei der Anzeige: Debugging und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben