Auf dieser Seite wird erläutert, wie Sie Karten Widgets und UI-Elemente hinzufügen, damit Nutzer mit Ihrer Google Chat App interagieren können, z. B. indem sie auf eine Schaltfläche klicken oder Informationen senden.
Chat-Apps können die folgenden Chat-Oberflächen verwenden, um interaktive Karten zu erstellen:
- 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.
- Dialogfelder: Karten, die in Nachrichten und auf Startseiten in einem neuen Fenster geöffnet werden.
Wenn Nutzer mit Karten interagieren, können Chat-Apps die empfangenen Daten verwenden, um sie zu verarbeiten und entsprechend zu reagieren. Weitere Informationen finden Sie unter Informationen von Google Chat-Nutzern erheben und verarbeiten.
Mit dem Card Builder können Sie Nachrichten und Benutzeroberflächen für Chat-Apps entwerfen und als Vorschau anzeigen lassen:
Karten-Tool öffnenVorbereitung
Eine Google Chat-App, für die interaktive Funktionen aktiviert sind. Wenn Sie eine interaktive Chat-App erstellen möchten, führen Sie einen der folgenden Schnellstarts aus, der auf der gewünschten App-Architektur basiert:
- HTTP-Dienst mit Google Cloud Functions
- Google Apps Script
- Google Cloud Dialogflow CX
- Cloud Pub/Sub
Schaltfläche hinzufügen
Im ButtonList
-Widget werden mehrere Schaltflächen angezeigt. Schaltflächen können Text, ein Symbol oder sowohl Text als auch ein Symbol anzeigen. Jede 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 ausführt, z. B. das Aufrufen einer API.
Aus Gründen der Barrierefreiheit unterstützen Schaltflächen alternativen Text.
Schaltfläche zum Ausführen einer benutzerdefinierten Funktion hinzufügen
Im Folgenden sehen Sie eine Karte mit einem ButtonList
-Widget mit zwei Schaltflächen.
Über nur eine Schaltfläche wird die Entwicklerdokumentation für Google Chat in einem neuen Tab geöffnet. Die andere Schaltfläche führt eine benutzerdefinierte Funktion namens goToView()
aus und übergibt den Parameter viewType="BIRD EYE VIEW"
.
Schaltfläche im Material Design-Stil hinzufügen
Im Folgenden sehen Sie eine Reihe von Schaltflächen in verschiedenen Material Design-Schaltflächenstile.
Um einen Material Design-Stil anzuwenden, lassen Sie das Attribut 'Farbe' [color] weg.
Schaltfläche mit benutzerdefinierter Farbe und deaktivierte Schaltfläche hinzufügen
Sie können verhindern, dass Nutzer auf eine Schaltfläche klicken, indem Sie "disabled": "true"
festlegen.
Im Folgenden sehen Sie eine Karte, die aus einem ButtonList
-Widget mit zwei Schaltflächen besteht. Für eine 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 auf die Schaltfläche klicken und die Funktion ausführen kann.
Schaltfläche mit einem Symbol hinzufügen
Die folgende Karte zeigt eine Karte, die aus einem ButtonList
-Widget mit zwei Symbol-Button
-Widgets besteht. Auf einer Schaltfläche wird das integrierte E-Mail-Symbol von Google Chat mit dem Feld knownIcon
angezeigt. Bei der anderen Schaltfläche wird das Feld iconUrl
verwendet, um ein benutzerdefiniertes Symbol-Widget anzuzeigen.
Schaltfläche mit Symbol und Text hinzufügen
Im Folgenden wird eine Karte mit einem ButtonList
-Widget angezeigt, das den Nutzer auffordert, eine E-Mail zu senden. Die erste Schaltfläche zeigt ein E-Mail-Symbol und die zweite Schaltfläche Text an. Der Nutzer kann entweder auf das Symbol oder auf die Textschaltfläche klicken, um die sendEmail
-Funktion auszuführen.
Schaltfläche für einen minimierbaren Bereich anpassen
Passen Sie die Steuerungsschaltfläche zum Minimieren und Maximieren von Abschnitten auf einer Karte an. Sie können aus einer Reihe von Symbolen oder Bildern auswählen, um den Inhalt des Abschnitts visuell darzustellen. So können Nutzer die Informationen leichter verstehen und mit ihnen interagieren.
Dreipunkt-Menü hinzufügen
Das Dreipunkt-Menü Overflow menu
kann in Google Chat-Karten verwendet werden, um zusätzliche Optionen und Aktionen anzubieten. So können Sie mehr Optionen hinzufügen, ohne die Oberfläche der Karte überladen zu müssen, was für ein klares und strukturiertes Design sorgt.
Chipsliste hinzufügen
Das ChipList
-Widget bietet eine vielseitige und visuell ansprechende Darstellung von Informationen.
Verwenden Sie Chiplisten, um Tags, Kategorien oder andere relevante Daten darzustellen. So können Nutzer einfacher auf Ihre Inhalte zugreifen und mit ihnen interagieren.
Informationen von Nutzern erheben
In diesem Abschnitt wird erläutert, wie Sie Widgets hinzufügen, die Informationen wie Text oder Auswahl erfassen.
Informationen zum Verarbeiten der Nutzereingaben finden Sie unter Informationen von Google Chat-Nutzern erfassen und verarbeiten.
Text erfassen
Das TextInput
-Widget bietet ein Feld, in das Nutzer Text eingeben können. Das Widget unterstützt Vorschläge, die Nutzern helfen, einheitliche Daten einzugeben, und Änderungsaktionen,Actions
die ausgeführt werden, wenn sich das Texteingabefeld ändert, z. B. wenn ein Nutzer Text hinzufügt oder löscht.
Wenn Sie abstrakte oder unbekannte Daten von Nutzern erheben möchten, verwenden Sie dieses TextInput
-Widget. Verwenden Sie stattdessen das SelectionInput
-Widget, um definierte Daten von Nutzern zu erfassen.
Die folgende Karte besteht aus einem TextInput
-Widget:
Datumsangaben oder Uhrzeiten erheben
Im DateTimePicker
-Widget können Nutzer ein Datum, eine Uhrzeit oder beides eingeben. Alternativ können Nutzer das Datum und die Uhrzeit über die Auswahl auswählen. Wenn Nutzer ein ungültiges Datum oder eine ungültige Uhrzeit eingeben, wird in der Auswahl ein Fehler angezeigt, der Nutzer auffordert, die Informationen korrekt einzugeben.
Die folgende Karte zeigt eine Karte, die aus drei verschiedenen Arten von DateTimePicker
-Widgets besteht:
Nutzern die Auswahl von Elementen ermöglichen
Das Widget SelectionInput
bietet eine Reihe von auswählbaren Elementen wie Kästchen, Optionsfelder, Schalter oder Drop-down-Menüs. Mit diesem Widget können Sie definierte und standardisierte Daten von Nutzern erfassen. Wenn Sie nicht definierte Daten von Nutzern erheben möchten, verwenden Sie stattdessen das Widget TextInput
.
Das SelectionInput
-Widget unterstützt Vorschläge, mit denen Nutzer einheitliche Daten eingeben können, sowie Aktionen bei Änderungen, bei denen es sich um Actions
-Aktionen handelt, die ausgeführt werden, wenn eine Änderung in einem Auswahleingabefeld erfolgt, z. B. wenn ein Nutzer ein Element auswählt oder die Auswahl wieder aufhebt.
Chat-Apps können den Wert ausgewählter Elemente empfangen und verarbeiten. Weitere Informationen zur Arbeit mit Formularinputs finden Sie unter Von Nutzern eingegebene Informationen verarbeiten.
In diesem Abschnitt finden Sie Beispiele für Karten, in denen das SelectionInput
-Widget verwendet wird.
In den Beispielen werden verschiedene Arten von Abschnittseingaben verwendet:
Kästchen hinzufügen
Im Folgenden wird eine Karte mit einem SelectionInput
-Widget mit Kästchen angezeigt, über das der Nutzer angeben kann, ob ein Kontakt geschäftlich, privat oder beides ist:
Optionsfeld hinzufügen
Im Folgenden wird eine Karte angezeigt, auf der der Nutzer mithilfe eines SelectionInput
-Widgets, das Optionsfelder verwendet, anzugeben, ob es sich um einen professionellen oder persönlichen Kontakt handelt:
Schalter hinzufügen
Im Folgenden wird eine Karte angezeigt, auf der der Nutzer mithilfe eines SelectionInput
-Widgets, das Schalter verwendet, anzugeben, ob es sich um einen geschäftlichen Kontakt, einen persönlichen oder beides handelt:
Drop-down-Menü hinzufügen
Im Folgenden wird eine Karte mit einem SelectionInput
-Widget mit Drop-down-Menü angezeigt, über das der Nutzer angeben kann, ob ein Kontakt geschäftlich oder privat ist:
Mehrfachauswahlmenü hinzufügen
Im Folgenden wird eine Karte angezeigt, auf der der Nutzer Kontakte aus einem Mehrfachauswahlmenü auswählen soll:
Sie können Elemente für ein Mehrfachauswahlmenü aus den folgenden Datenquellen in Google Workspace füllen:
- Google Workspace-Nutzer: Sie können nur Nutzer innerhalb derselben Google Workspace-Organisation einfügen.
- Chatbereiche: Der Nutzer, der Elemente in das Mehrfachauswahlmenü eingibt, kann nur Gruppenbereiche ansehen und auswählen, denen er in seiner Google Workspace-Organisation angehö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ü mit Google Workspace-Nutzern.
Um Nutzer einzufügen, wird in der Auswahleingabe 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 Mehrfachauswahlmenü für Gruppenbereiche. Zum Ausfüllen von Gruppenbereichen wird in der Auswahleingabe das Feld hostAppDataSource
angegeben. Im Mehrfachauswahl-Menü wird defaultToCurrentSpace
außerdem 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
}
}
}
}
}
}
In Menüs mit Mehrfachauswahl können auch Elemente aus einer Drittanbieter- oder externen Datenquelle eingefügt werden. Sie können beispielsweise Mehrfachauswahlmenüs verwenden, um einem Nutzer die Auswahl aus einer Liste von Leads aus einem CRM-System (Customer-Relationship-Management) zu erleichtern.
Wenn Sie eine externe Datenquelle verwenden möchten, geben Sie im Feld externalDataSource
eine Funktion an, die Elemente aus der Datenquelle zurückgibt.
Um die Anzahl der Anfragen an eine externe Datenquelle zu reduzieren, können Sie Vorschläge einfügen, die im Mehrfachauswahlmenü angezeigt werden, bevor Nutzer etwas eingeben. Sie können beispielsweise die zuletzt gesuchten Kontakte für den Nutzer einblenden. Wenn Sie vorgeschlagene Elemente aus einer externen Datenquelle einfügen möchten, geben Sie SelectionItem
-Objekte an.
Der folgende Code zeigt ein Mehrfachauswahl-Menü mit Elementen aus einer externen Gruppe von Kontakten für den Nutzer. Im Menü wird standardmäßig ein Kontakt angezeigt und die Funktion getContacts
wird ausgeführt, um Elemente aus der externen Datenquelle abzurufen und einzufügen:
Node.js
Python
Java
Apps Script
Bei externen Datenquellen können Sie Elemente, die Nutzer im Mehrfachauswahlmenü eingeben, auch automatisch vervollständigen. Wenn ein Nutzer beispielsweise Atl
für ein Menü eingibt, in dem Städte in den USA angezeigt werden, kann Ihre Chat-App Atlanta
automatisch vorschlagen, bevor der Nutzer fertig ist. Sie können bis zu 100 Elemente automatisch vervollständigen.
Zur automatischen Vervollständigung von Elementen erstellen Sie eine Funktion, die die externe Datenquelle abfragt und Elemente zurückgibt, wenn ein Nutzer das Mehrfachauswahlmenü eingibt. Die Funktion muss Folgendes tun:
- Übergeben Sie ein Ereignisobjekt, das die Nutzerinteraktion mit dem Menü darstellt.
- Prüfen Sie, ob der Wert
invokedFunction
des Interaktionsereignisses mit der Funktion aus dem FeldexternalDataSource
übereinstimmt. - Wenn die Funktionen übereinstimmen, werden Vorschläge aus der externen Datenquelle zurückgegeben. Wenn Sie Elemente basierend auf dem Nutzertyp vorschlagen möchten, rufen Sie den Wert für den Schlüssel
autocomplete_widget_query
ab. Dieser Wert gibt an, was der Nutzer im Menü eingibt.
Mit dem folgenden Code werden Elemente aus einer externen Datenressource automatisch vervollständigt. Im vorherigen Beispiel schlägt die Chat-App Elemente vor, je nachdem, wann die Funktion getContacts
ausgelöst wird:
Node.js
Python
Java
Apps Script
Auf Karten eingegebene Daten validieren
Auf dieser Seite wird beschrieben, wie Sie Daten validieren, die in die action
und Widgets einer Karte eingegeben wurden.
Sie können beispielsweise prüfen, ob ein Texteingabefeld vom Nutzer eingegebenen Text enthält oder eine bestimmte Anzahl von Zeichen.
Erforderliche Widgets für Aktionen festlegen
Füge in die action
-Liste der Karte die Namen von Widgets, die eine Aktion benötigt, der requiredWidgets
-Liste hinzu.
Wenn hier aufgeführte Widgets beim Aufrufen dieser Aktion keinen Wert haben, wird das Senden der Formularaktion abgebrochen.
Wenn "all_widgets_are_required": "true"
für eine Aktion festgelegt ist, werden alle Widgets auf der Karte für diese Aktion benötigt.
all_widgets_are_required
-Aktion für die Mehrfachauswahl festlegen
JSON
{
"sections": [
{
"header": "Select contacts",
"widgets": [
{
"selectionInput": {
"type": "MULTI_SELECT",
"label": "Selected contacts",
"name": "contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"onChangeAction": {
"all_widgets_are_required": true
},
"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
}
]
}
}
]
}
]
}
all_widgets_are_required
-Aktion in dateTimePicker festlegen
JSON
{
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "A datetime picker widget with both date and time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_and_time",
"label": "meeting",
"type": "DATE_AND_TIME"
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just date:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_only",
"label": "Choose a date",
"type": "DATE_ONLY",
"onChangeAction":{
"all_widgets_are_required": true
}
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_time_only",
"label": "Select a time",
"type": "TIME_ONLY"
}
}
]
}
]
}
all_widgets_are_required
-Aktion im Drop-down-Menü festlegen
JSON
{
"sections": [
{
"header": "Section Header",
"collapsible": true,
"uncollapsibleWidgetsCount": 1,
"widgets": [
{
"selectionInput": {
"name": "location",
"label": "Select Color",
"type": "DROPDOWN",
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"text": "Red",
"value": "red",
"selected": false
},
{
"text": "Green",
"value": "green",
"selected": false
},
{
"text": "White",
"value": "white",
"selected": false
},
{
"text": "Blue",
"value": "blue",
"selected": false
},
{
"text": "Black",
"value": "black",
"selected": false
}
]
}
}
]
}
]
}
Validierung für ein Widget für die Texteingabe festlegen
Im Validierungsfeld des textInput
-Widgets können die Zeichenbeschränkung und der Eingabetyp für dieses Texteingabe-Widget angegeben werden.
Zeichenbeschränkung für ein Texteingabe-Widget festlegen
JSON
{
"sections": [
{
"header": "Tell us about yourself",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "favoriteColor",
"label": "Favorite color",
"type": "SINGLE_LINE",
"validation": {"character_limit":15},
"onChangeAction":{
"all_widgets_are_required": true
}
}
}
]
}
]
}
Eingabetyp für ein Widget für die Texteingabe festlegen
JSON
{
"sections": [
{
"header": "Validate text inputs by input types",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "mailing_address",
"label": "Please enter a valid email address",
"type": "SINGLE_LINE",
"validation": {
"input_type": "EMAIL"
},
"onChangeAction": {
"all_widgets_are_required": true
}
}
},
{
"textInput": {
"name": "validate_integer",
"label": "Please enter a number",
"type": "SINGLE_LINE",
"validation": {
"input_type": "INTEGER"
}
}
},
{
"textInput": {
"name": "validate_float",
"label": "Please enter a number with a decimal",
"type": "SINGLE_LINE",
"validation": {
"input_type": "FLOAT"
}
}
}
]
}
]
}
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.