Eine interaktive Karte oder ein interaktives Dialogfeld entwerfen

Auf dieser Seite wird erläutert, wie Sie Widgets und UI-Elemente zu Karten- oder Dialogfeldmeldungen hinzufügen, damit Nutzer mit Ihrer Google Chat-App interagieren können, z. B. durch Klicken auf eine Schaltfläche oder durch Senden von Informationen.


Mit dem Card Builder kannst du Karten entwerfen und sie dir als Vorschau ansehen.

Den Card Builder öffnen

Voraussetzungen

  • Ein Google Workspace-Konto mit Zugriff auf Google Chat.
  • Eine veröffentlichte Chat-App. Folgen Sie dieser quickstart, um eine Chat-App zu erstellen.
  • Schaltfläche hinzufügen

    Das ButtonList-Widget zeigt eine Reihe von Schaltflächen an. Schaltflächen können Text, ein Symbol oder beides anzeigen. Jedes Button unterstützt eine OnClick-Aktion, die ausgeführt wird, wenn Nutzer auf die Schaltfläche klicken. Beispiel:

    • Öffnen Sie einen Hyperlink mit OpenLink, um Nutzern zusätzliche Informationen bereitzustellen.
    • Führen Sie einen action aus, der eine benutzerdefinierte Funktion wie den Aufruf einer API ausführt.

    Aus Gründen der Barrierefreiheit unterstützen Schaltflächen alternativen Text.

    Schaltfläche zum Ausführen einer benutzerdefinierten Funktion hinzufügen

    Die folgende Karte besteht aus einem ButtonList-Widget mit zwei Schaltflächen. Mit nur einer Schaltfläche wird die Entwicklerdokumentation für Google Chat in einem neuen Tab geöffnet. Auf der anderen Schaltfläche wird eine benutzerdefinierte Funktion namens goToView() ausgeführt und der Parameter viewType="BIRD EYE VIEW" übergeben.

    Eine Schaltfläche mit benutzerdefinierter Farbe und eine deaktivierte Schaltfläche hinzufügen

    Du kannst verhindern, dass Nutzer auf eine Schaltfläche klicken, indem du "disabled": "true" festlegst.

    Im Folgenden wird eine Karte angezeigt, die aus einem ButtonList-Widget mit zwei Schaltflächen besteht. Bei einer Schaltfläche wird das Feld Color verwendet, um die Hintergrundfarbe der Schaltfläche anzupassen. Die andere Schaltfläche wird mit dem Feld Disabled deaktiviert, sodass der Nutzer nicht darauf klicken und die Funktion ausführen kann.

    Schaltfläche mit Symbol hinzufügen

    Im Folgenden wird eine Karte angezeigt, die aus einem ButtonList-Widget mit zwei Symbol-Button-Widgets besteht. Auf einer Schaltfläche wird über das Feld knownIcon das in Google Chat integrierte E-Mail-Symbol angezeigt. Auf der anderen Schaltfläche wird das Feld iconUrl verwendet, um ein Widget für benutzerdefinierte Symbole anzuzeigen.

    Schaltfläche mit Symbol und Text hinzufügen

    Im Folgenden wird eine Karte mit einem ButtonList-Widget angezeigt, über das der Nutzer zum Senden einer E-Mail aufgefordert wird. Die erste Schaltfläche enthält ein E-Mail-Symbol und die zweite Schaltfläche Text. Der Nutzer kann entweder auf das Symbol oder die Textschaltfläche klicken, um die Funktion sendEmail auszuführen.

    Auswählbare UI-Elemente hinzufügen

    Das SelectionInput-Widget bietet eine Reihe von auswählbaren Elementen, z. B. Kästchen, Optionsfelder, Schalter oder Drop-down-Menüs. Mit diesem Widget können Sie definierte und standardisierte Daten von Nutzern erfassen. Verwenden Sie stattdessen das TextInput-Widget, um nicht definierte Daten von Nutzern zu erfassen.

    Das SelectionInput-Widget unterstützt Vorschläge, mit denen Nutzer einheitliche Daten eingeben können, sowie Aktionen bei Änderung. Dabei handelt es sich um Actions, die ausgeführt werden, wenn in einem Auswahlfeld eine Änderung vorgenommen wird, z. B. wenn ein Nutzer ein Element auswählt oder die Auswahl aufhebt.

    Chat-Apps können den Wert ausgewählter Elemente empfangen und verarbeiten. Weitere Informationen zum Arbeiten mit Formulareingaben finden Sie unter Formulardaten empfangen.

    Dieser Abschnitt enthält Beispiele für Karten, auf denen das SelectionInput-Widget verwendet wird. In den Beispielen werden verschiedene Arten von Abschnittseingaben verwendet:

    Kästchen hinzufügen

    Im folgenden Dialogfeld wird der Nutzer aufgefordert, mit einem SelectionInput-Widget, das Kästchen verwendet, anzugeben, ob es sich um einen professionellen Kontakt, einen privaten Kontakt oder beides handelt:

    Optionsfeld hinzufügen

    Im folgenden Dialogfeld wird der Nutzer aufgefordert, über ein SelectionInput-Widget, das Optionsfelder verwendet, anzugeben, ob es sich um einen professionellen oder privaten Kontakt handelt:

    Schalter hinzufügen

    Im folgenden Dialogfeld wird der Nutzer aufgefordert, mit einem SelectionInput-Widget, das Schalter verwendet, anzugeben, ob es sich um einen professionellen Kontakt, einen privaten Kontakt oder beides handelt:

    Im folgenden Dialogfeld wird der Nutzer aufgefordert, über ein SelectionInput-Widget, das ein Drop-down-Menü verwendet, anzugeben, ob es sich um einen professionellen oder privaten Kontakt handelt:

    Mehrfachauswahlmenü hinzufügen

    Im folgenden Dialogfeld wird der Nutzer aufgefordert, Kontakte aus einem Mehrfachauswahlmenü auszuwählen:

    Datenquellen für Mehrfachauswahl-Menüs verwenden

    Im folgenden Abschnitt wird erläutert, wie Sie mithilfe von Mehrfachauswahl-Menüs Daten aus dynamischen Quellen wie einer Google Workspace-Anwendung oder einer externen Datenquelle einfügen können.

    Datenquellen aus Google Workspace

    Sie können Elemente für ein Mehrfachauswahl-Menü aus den folgenden Datenquellen in Google Workspace ausfüllen:

    • Google Workspace-Nutzer: Sie können nur Nutzer in derselben Google Workspace-Organisation ausfüllen.
    • Chatbereiche: Der Nutzer, der Elemente im Mehrfachauswahl-Menü eingibt, kann nur Gruppenbereiche aufrufen und auswählen, zu denen er innerhalb seiner Google Workspace-Organisation gehört.

    Wenn Sie Google Workspace-Datenquellen verwenden möchten, geben Sie das Feld platformDataSource an. Im Gegensatz zu anderen Auswahleingabetypen lassen Sie SectionItem-Objekte weg, da diese Auswahlelemente dynamisch aus Google Workspace stammen.

    Der folgende Code zeigt ein Mehrfachauswahlmenü von Google Workspace-Nutzern. Zum Ausfüllen von Nutzern wird commonDataSource auf USER gesetzt:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 1,
        "platformDataSource": {
          "commonDataSource": "USER"
        }
      }
    }
    

    Der folgende Code zeigt ein Mehrfachauswahl-Menü mit Chatbereichen. Zum Ausfüllen von Bereichen wird mit der Auswahl das Feld hostAppDataSource definiert. Im Mehrfachauswahl-Menü wird außerdem defaultToCurrentSpace auf true gesetzt. Dadurch wird der aktuelle Bereich zur Standardauswahl im Menü:

    JSON

    {
      "selectionInput": {
        "name": "spaces",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 3,
        "multiSelectMinQueryLength": 1,
        "platformDataSource": {
          "hostAppDataSource": {
            "chatDataSource": {
              "spaceDataSource": {
                "defaultToCurrentSpace": true
              }
            }
          }
        }
      }
    }
    
    Datenquellen außerhalb von Google Workspace

    Mit Mehrfachauswahl-Menüs können auch Elemente aus einer Drittanbieter- oder externen Datenquelle ausgefüllt werden. Sie können beispielsweise Mehrfachauswahl-Menüs verwenden, um einem Nutzer zu helfen, aus einer Liste von Vertriebs-Leads aus einem CRM-System (Customer-Relationship-Management) auszuwählen.

    Wenn Sie eine externe Datenquelle verwenden möchten, geben Sie im Feld externalDataSource eine Funktion an, die Elemente aus der Datenquelle zurückgibt.

    Wenn Sie die Anzahl der Anfragen an eine externe Datenquelle reduzieren möchten, können Sie vorgeschlagene Elemente hinzufügen, die im Mehrfachauswahl-Menü angezeigt werden, bevor der Nutzer etwas im Menü eingibt. So können Sie beispielsweise kürzlich gesuchte Kontakte für den Nutzer ausfüllen. Wenn Sie vorgeschlagene Elemente aus einer externen Datenquelle füllen möchten, geben Sie SelectionItem-Objekte an.

    Der folgende Code zeigt ein Mehrfachauswahl-Menü mit Elementen aus einem externen Satz von Kontakten für den Nutzer. Das Menü zeigt standardmäßig einen Kontakt an und führt die Funktion getContacts aus, um Elemente aus der externen Datenquelle abzurufen und auszufüllen:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 2,
        "externalDataSource": {
          "function": "getContacts"
        },
        "items": [
          {
            "text": "Contact 3",
            "value": "contact-3",
            "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
            "bottomText": "Contact three description",
            "selected": false
          }
        ]
      }
    }
    

    Bei externen Datenquellen können Sie Elemente, die Nutzer eintippen, im Mehrfachauswahlmenü auch automatisch vervollständigen. Wenn ein Nutzer beispielsweise anfängt, Atl für ein Menü einzugeben, das Städte in den USA ausfüllt, kann Ihre Chat-App Atlanta automatisch vorschlagen, bevor der Nutzer mit der Eingabe fertig ist. Sie können bis zu 100 Einträge automatisch vervollständigen.

    Zum automatischen Vervollständigen von Elementen erstellen Sie eine Funktion, die die externe Datenquelle abfragt und Elemente zurückgibt, wenn ein Nutzer eine Eingabe in das Mehrfachauswahl-Menü eingibt. Die Funktion muss folgende Voraussetzungen erfüllen:

    • Übergeben Sie ein Ereignisobjekt, das die Nutzerinteraktion mit dem Menü darstellt.
    • Prüfen Sie, ob der Wert invokedFunction des Interaktionsereignisses mit der Funktion im Feld externalDataSource übereinstimmt.
    • Wenn die Funktionen übereinstimmen, werden vorgeschlagene Elemente aus der externen Datenquelle zurückgegeben. Wenn Sie Elemente basierend auf den Eingaben des Nutzers vorschlagen möchten, rufen Sie den Wert für den Schlüssel autocomplete_widget_query ab. Dieser Wert stellt dar, was der Nutzer im Menü eingibt.

    Mit dem folgenden Code werden Elemente aus einer externen Datenressource automatisch vervollständigt. Unter Verwendung des vorherigen Beispiels schlägt die Chat-App Elemente basierend darauf vor, wann die Funktion getContacts ausgelöst wird:

    Apps Script

    apps-script/selection-input/on-widget-update.gs
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              items: [
                {
                  value: "contact-1",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 1",
                  bottomText: "Contact one description",
                  selected: false
                },
                {
                  value: "contact-2",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 2",
                  bottomText: "Contact two description",
                  selected: false
                },
                {
                  value: "contact-3",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 3",
                  bottomText: "Contact three description",
                  selected: false
                },
                {
                  value: "contact-4",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 4",
                  bottomText: "Contact four description",
                  selected: false
                },
                {
                  value: "contact-5",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 5",
                  bottomText: "Contact five description",
                  selected: false
                },
              ]
            }
          }
        }
      };
    }
    

    Node.js

    node/selection-input/on-widget-update.js
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              items: [
                {
                  value: "contact-1",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 1",
                  bottomText: "Contact one description",
                  selected: false
                },
                {
                  value: "contact-2",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 2",
                  bottomText: "Contact two description",
                  selected: false
                },
                {
                  value: "contact-3",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 3",
                  bottomText: "Contact three description",
                  selected: false
                },
                {
                  value: "contact-4",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 4",
                  bottomText: "Contact four description",
                  selected: false
                },
                {
                  value: "contact-5",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 5",
                  bottomText: "Contact five description",
                  selected: false
                },
              ]
            }
          }
        }
      };
    }
    

    Feld hinzufügen, in das ein Nutzer Text eingeben kann

    Das TextInput-Widget bietet ein Feld, in das Nutzer Text eingeben können. Das Widget unterstützt Vorschläge, mit denen Nutzer einheitliche Daten eingeben können, sowie Aktionen bei Änderung, bei denen es sich um Actions handelt, die ausgeführt werden, wenn eine Änderung im Texteingabefeld vorgenommen wird, z. B. wenn ein Nutzer Text hinzufügt oder löscht.

    Wenn Sie abstrakte oder unbekannte Daten von Nutzern erfassen möchten, verwenden Sie dieses TextInput-Widget. Verwenden Sie stattdessen das SelectionInput-Widget, um definierte Daten von Nutzern zu erfassen.

    Weitere Informationen zum Verarbeiten des von Nutzern eingegebenen Textes finden Sie unter Formulardaten empfangen.

    Die folgende Karte besteht aus einem TextInput-Widget:

    Nutzer dürfen Datum und Uhrzeit auswählen

    Im DateTimePicker-Widget können Nutzer ein Datum, eine Uhrzeit oder sowohl ein Datum als auch eine Uhrzeit eingeben. Nutzer können auch die Auswahl verwenden, um Datum und Uhrzeit festzulegen. Wenn Nutzer ein ungültiges Datum oder eine ungültige Uhrzeit eingeben, zeigt die Auswahl einen Fehler an, der den Nutzer auffordert, die Informationen richtig einzugeben.

    Informationen zum Verarbeiten der von Nutzern eingegebenen Datums- und Uhrzeitwerte finden Sie unter Formulardaten empfangen.

    Im Folgenden wird eine Karte mit drei verschiedenen Arten von DateTimePicker-Widgets angezeigt:

    Fehlerbehebung

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

    Obwohl eine Fehlermeldung möglicherweise nicht in der Chat-Benutzeroberfläche angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, mit denen Sie Fehler beheben können, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Aufrufen, Debuggen und Beheben von Fehlern finden Sie im Hilfeartikel Google Chat-Fehler beheben.