Informationen von Google Chat-Nutzern erheben und verarbeiten

In diesem Leitfaden wird beschrieben, wie Google Chat-Apps Informationen von Nutzern erfassen und verarbeiten können, indem sie Formulareingaben in kartenbasierten Oberflächen erstellen.

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 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 Ermöglichen Sie beispielsweise Nutzern, einen Termin in Google Kalender zu erstellen.
  • Nutzern erlauben, auf Ressourcen in anderen Apps oder Webdiensten zuzugreifen und sie zu aktualisieren Mit einer Chat-App können Nutzer beispielsweise den Status eines Support-Tickets direkt in einem Chatbereich aktualisieren.

Vorbereitung

Node.js

Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Führen Sie diese Kurzanleitung aus, um eine interaktive Chat-App mit einem HTTP-Dienst zu erstellen.

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: Dies ist eine Karte, die in Direktnachrichten mit der Chat App auf dem Tab Startseite angezeigt wird.
  • Dialoge: Karten, die in einem neuen Fenster von Nachrichten und Startseiten aus geöffnet werden.

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

  • Formular-Eingabe-Widgets, über die Nutzer um Informationen gebeten werden. Optional können Sie Validierungsregeln für Formular-Eingabe-Widgets hinzufügen, damit Nutzer Informationen korrekt eingeben und formatieren. Chat-Apps können die folgenden Formulareingabe-Widgets verwenden:

    • 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 Chatbereiche, in denen sie Mitglied sind, aus einer Liste auswählen.
    • 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 eines Auswahleingabe-Widgets erfasst:

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 beliebigen Werten, die der Nutzer eingibt.

Sie können die Werte aus dem Objekt common.formInputs.WIDGET_NAME abrufen, wobei WIDGET_NAME das Feld name ist, 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 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 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:

  • Unterstützen Sie Nutzer beim Ausfüllen längerer Formulare, indem Sie separate Abschnitte erstellen.
  • 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. Um Nutzer beispielsweise dazu aufzufordern, einen Termin zu erstellen, könnte eine Chat-App eine erste Karte anzeigen, die den Grund für den Termin anfordert, und dann eine andere Karte mit den verfügbaren Zeiten je nach Termintyp ausfüllen.

Um die Dateneingabe von der ersten Karte zu übertragen, kannst du das button-Widget mit actionParameters erstellen, das die name des Widgets und den Wert enthält, den der Nutzer eingibt, 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 einem Fehler.

Im folgenden Beispiel sendet eine Chat-App eine SMS, um zu bestätigen, dass sie ein Formular erfolgreich empfangen hat, das über eine Dialog- oder Kartennachricht gesendet 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-Oberflä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 eine Kartennachricht möglicherweise nicht 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.