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 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 mit einer Chat-App beispielsweise den Status eines Supporttickets direkt über einen Chatbereich aktualisieren.

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. Wenn Sie eine interaktive Chat-App mit einem HTTP-Dienst erstellen möchten, folgen Sie dieser Kurzanleitung.

Java

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.

Apps Script

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App in Apps Script erstellen möchten, folgen Sie dieser Kurzanleitung.

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:

  • 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 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:

    • Textfelder (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.
    • Datums- und Uhrzeitauswahl (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:

Im folgenden Code sehen Sie ein Beispiel für eine Chat-App, in der dieses Kontaktformular verwendet wird:

Node.js

node/contact-form-app/index.js
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py
# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Script

apps-script/contact-form-app/contactForm.gs
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

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 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 sehen Sie einen Teil eines CARD_CLICKED-Interaktionsereignisses, bei dem 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 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 Interaktionsereignis gespeichert wird, und ein Beispielwert.

Widget für die Formulareingabe Datentyp der Eingabe Eingabewert aus dem Interaktionsereignis Beispielwert
textInput stringInputs event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Um den ersten oder einzigen Wert zu erhalten, event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker, in dem nur Datumsangaben zulässig sind. dateInput event.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.
  • Die restlichen Teile des Formulars werden dynamisch ausgefüllt. Wenn Sie Nutzer beispielsweise dazu auffordern möchten, 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:

Node.js

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Script

apps-script/contact-form-app/main.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Wenn ein Nutzer auf die Schaltfläche klickt, empfängt Ihre Chat-App ein CARD_CLICKED-Interaktionsereignis, von dem Sie Daten empfangen können.

Auf ein eingereichtes Formular 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 einen Dialog oder eine Kartennachricht gesendet wurde, erfolgreich empfangen wurde.

Node.js

node/contact-form-app/index.js
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

Python

python/contact-form-app/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
if contact_name == "":
  error_message = "Don't forget to name your new contact!"
  if "SUBMIT_DIALOG" == event.get('dialogEventType'):
    return { 'actionResponse': {
      'type': "DIALOG",
      'dialogAction': { 'actionStatus': {
        'statusCode': "INVALID_ARGUMENT",
        'userFacingMessage': error_message
      }}
    }}
  else:
    return {
      'privateMessageViewer': event.get('user'),
      'text': error_message
    }

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (contactName.isEmpty()) {
  String errorMessage = "Don't forget to name your new contact!";
  if (event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
    return new Message().setActionResponse(new ActionResponse()
      .setType("DIALOG")
      .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
        .setStatusCode("INVALID_ARGUMENT")
        .setUserFacingMessage(errorMessage))));
  } else {
    return new Message()
      .setPrivateMessageViewer(new User().setName(event.at("/user/name").asText()))
      .setText(errorMessage);
  }
}

Apps Script

apps-script/contact-form-app/main.gs
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

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