In diesem Leitfaden werden häufige Fehler im Zusammenhang mit Karten und deren Behebung beschrieben.
Mit dem Card Builder können Sie JSON-Kartennachrichten für Chat-Apps erstellen und als Vorschau ansehen:
Card Builder öffnenSo werden Kartenfehler angezeigt
Kartenfehler können auf verschiedene Arten auftreten:
- Ein Teil einer Karte, z. B. ein Widget oder eine Komponente, erscheint nicht oder wird auf unerwartete Weise gerendert.
- Es wird nicht die gesamte Karte angezeigt.
- Ein Dialogfeld wird geschlossen, nicht geöffnet oder nicht geladen.
Wenn Sie ein solches Verhalten feststellen, liegt ein Fehler in der Karte Ihrer App vor.
Zur Info: Eine funktionierende, fehlerfreie Kartennachricht und ein entsprechendes Dialogfeld
Bevor Sie sich mit fehlerhaften Kartenbeispielen befassen, betrachten Sie zuerst diese funktionierende Kartennachricht und das entsprechende Dialogfeld. Um jeden Beispielfehler und seine Behebung zu veranschaulichen, wird der JSON-Code dieser Karte durch Fehler geändert.
Fehlermeldung ohne Fehler
Hier ist die funktionierende, fehlerfreie Kartennachricht mit den Kontaktdaten, die enthält eine Kopfzeile, Abschnitte und Widgets wie dekorierten Text und Schaltflächen:
Fehlerfreies Dialogfeld
Hier sehen Sie ein funktionierendes, fehlerfreies Dialogfeld, in dem ein Kontakt Informationen von Nutzenden, mit einer Fußzeile und bearbeitbaren Widgets wie Texteingabe und Schaltern sowie Tasten:
Fehler: Ein Teil einer Karte wird nicht angezeigt
Manchmal werden Karten gerendert, aber ein Teil einer Karte, den Sie erwartet haben, wird nicht angezeigt. Mögliche Ursachen:
- Ein erforderliches JSON-Feld fehlt.
- Ein JSON-Feld wurde falsch geschrieben oder falsch geschrieben.
Ursache: Erforderliches JSON-Feld fehlt
In diesem Beispielfehler fehlt ein erforderliches JSON-Feld (title
). Die Karte wird daher gerendert, aber Teile der Karte, die eigentlich zu sehen sein sollten, erscheinen nicht. Es kann schwierig sein, vorherzusagen, wie Karten gerendert werden, wenn Pflichtfelder weggelassen werden.
Fügen Sie das erforderliche JSON-Feld hinzu, um diesen Fehler zu beheben: in diesem Beispiel title
.
Ob ein JSON-Feld erforderlich ist, erfährst du in der Referenzdokumentation zu Karten v2. Sehen Sie sich in diesem Beispiel die Beschreibung des Felds title
auf CardHeader
an.
Hier sind zwei Beispiele:
Beispiel 1: Wenn Sie subtitle
angeben, aber das erforderliche title
weglassen, erscheint der gesamte Header leer:
<ph type="x-smartling-placeholder">![Die Kopfzeile dieser Karte wird nicht angezeigt, weil ein Pflichtfeld (Titel) fehlt.](https://google-developers.gonglchuangl.net/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-1.png?authuser=0&hl=de)
title
) fehlt.Fehlerhaftes JSON-Snippet einer Karte ansehen
Fehler: In header
fehlt das Pflichtfeld title
.
. . . "header": { "subtitle": "Software Engineer" } . . .
Korrektes JSON-Karten-Snippet ansehen
Fest: Das Pflichtfeld title
ist Teil der header
-Spezifikation.
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer" } . . .
Beispiel 2: Wenn Sie subtitle
, imageUrl
, imageType
und imageAltText
angeben, aber das erforderliche title
weglassen, wird das Bild wie erwartet gerendert, aber nicht der Untertitel:
<ph type="x-smartling-placeholder">![Die Kopfzeile dieser Karte wird nicht angezeigt, weil ein Pflichtfeld (Titel) fehlt.](https://google-developers.gonglchuangl.net/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-2.png?authuser=0&hl=de)
title
) fehlt, das Bild aber wie erwartet gerendert wird.Fehlerhaftes JSON-Snippet einer Karte ansehen
Fehler: In header
fehlt das Pflichtfeld title
.
. . . "header": { "subtitle": "Software Engineer", "imageUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "imageType": "CIRCLE", "imageAltText": "Avatar for Sasha", } . . .
Korrektes JSON-Karten-Snippet ansehen
Fest: Das Pflichtfeld title
ist Teil der header
-Spezifikation.
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer", "imageUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "imageType": "CIRCLE", "imageAltText": "Avatar for Sasha", } . . .
Ursache: Falsche Schreibweise von JSON oder Großschreibung
In diesem Beispielfehler enthält die JSON-Karte alle erforderlichen Felder, aber das Feld imageUrl
ist falsch mit imageURL
großgeschrieben (R
mit L
groß). Das führt zu einem Fehler: Das Bild, auf das sie verweist, wird nicht gerendert.
Um diesen und andere Fehler zu beheben, verwenden Sie die richtige JSON-Formatierung. In diesem Fall ist imageUrl
korrekt. Vergleichen Sie im Zweifelsfall die JSON-Karte mit dem card-Referenzdokument.
![Die Kopfzeile dieser Karte wird nicht angezeigt, weil ein Pflichtfeld (Titel) fehlt.](https://google-developers.gonglchuangl.net/static/workspace/chat/images/troubleshoot/troubleshoot-cards-imageURL-instead-of-imageUrl.png?authuser=0&hl=de)
title
) fehlt, das Bild aber wie erwartet gerendert wird.Fehlerhaftes JSON-Snippet einer Karte ansehen
Fehler: Das Feld imageURL
enthält nicht die richtige Groß- und Kleinschreibung. Er sollte imageUrl
lauten.
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer", "imageURL": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "imageType": "CIRCLE", "imageAltText": "Avatar for Sasha", } . . .
Korrektes JSON-Karten-Snippet ansehen
Fest: Das Feld imageUrl
wurde richtig großgeschrieben.
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer", "imageUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "imageType": "CIRCLE", "imageAltText": "Avatar for Sasha", } . . .
Fehler: Es wird nicht die gesamte Karte angezeigt
Manchmal wird die Karte selbst nicht angezeigt. Mögliche Ursachen:
- Ein
ButtonList
-Widget ist falsch angegeben. - Ein
CardFixedFooter
-Widget hat eine falsch angegebene Schaltfläche.
Ursache: Falsche Angabe von buttonList
oder cardFixedFooter
Wenn eine Kartennachricht oder ein Dialogfeld ein falsch angegebenes ButtonList
-Widget oder ein CardFixedFooter
-Widget mit falsch angegebenen Schaltflächen enthält, wird die gesamte Karte nicht angezeigt und an ihrer Stelle nichts angezeigt. Falsche Spezifikationen können fehlende Felder, falsch geschriebene Felder oder Großschreibungen oder falsch strukturierte JSON-Daten sein, z. B. fehlende Kommas, Anführungszeichen oder geschweifte Klammern.
Vergleichen Sie die JSON-Karte der Karte mit dem Referenzdokument zu card, um diesen Fehler zu beheben. Vergleichen Sie insbesondere alle ButtonList
-Widgets mit der Widget-Übersicht für ButtonList
.
Beispiel:In einer ButtonList
-Widget-Übersicht wird durch die Übergabe einer unvollständigen onClick
-Aktion über die erste Schaltfläche verhindert, dass die gesamte Karte gerendert wird.
Fehlerhaftes Karten-JSON-Snippet ansehen
Fehler: Für das Objekt onClick
sind keine Felder angegeben, sodass nicht die gesamte Karte angezeigt wird.
. . . { "buttonList": { "buttons": [ { "text": "Share", "onClick": { } } }, { "text": "Edit", "onClick": { "action": { "function": "goToView", "parameters": [ { "key": "viewType", "value": "EDIT", } ], } } }, ], }, } . . .
Korrektes JSON-Karten-Snippet ansehen
Korrigiert: Das onClick
-Objekt verfügt jetzt über ein openLink
-Feld, sodass die Karte wie erwartet angezeigt wird.
. . . { "buttonList": { "buttons": [ { "text": "Share", "onClick": { "openLink": { "url": "https://example.com/share", } } }, { "text": "Edit", "onClick": { "action": { "function": "goToView", "parameters": [ { "key": "viewType", "value": "EDIT", } ], } } }, ], }, } . . .
Fehler: Ein Dialogfeld wird geschlossen, bleibt hängen oder öffnet sich nicht
Wenn ein Dialogfeld unerwartet geschlossen, nicht geladen oder nicht geöffnet wird, liegt wahrscheinlich ein Problem mit der Kartenoberfläche vor.
Das sind die häufigsten Gründe:
- Das
CardFixedFooter
-Widget enthält keineprimaryButton
. - Eine Schaltfläche im
CardFixedFooter
-Widget hat keine AktiononClick
oder die AktiononClick
wurde falsch angegeben. - Einem
TextInput
-Widget fehlt das Feldname
.
Ursache: CardFixedFooter
enthält keine primaryButton
In Dialogfeldern mit einem CardFixedFooter
-Widget muss ein primaryButton
sowohl mit Text als auch mit Farbe angegeben werden. Wenn Sie primaryButton
weglassen oder falsch festlegen, wird das gesamte Dialogfeld nicht angezeigt.
Um diesen Fehler zu beheben, muss das CardFixedFooter
-Widget eine korrekt angegebene primaryButton
enthalten.
Fehlerhaftes Karten-JSON-Snippet ansehen
Fehler: Für das Objekt fixedFooter
ist kein primaryButton
-Feld angegeben, sodass das Dialogfeld nicht geladen oder geöffnet werden kann.
. . . "fixedFooter": { "onClick": { . . . }, "secondaryButton": { . . . } } } . . .
Korrektes JSON-Karten-Snippet ansehen
Behoben: Für fixedFooter
ist jetzt ein primaryButton
-Feld angegeben, sodass das Dialogfeld wie erwartet funktioniert.
. . . "fixedFooter": { "primaryButton": { "text": "Submit", "color": { "red": 0, "blue": 1, "green": 0 }, "onClick": { . . . }, "secondaryButton": { . . . } } } . . .
Ursache: Falsche onClick
-Einstellung in FixedFooter
In Dialogfeldern mit einem CardFixedFooter
-Widget wird die Einstellung onClick
für eine Schaltfläche falsch angegeben oder weggelassen, wodurch das Dialogfeld geschlossen, nicht geladen oder nicht geöffnet werden kann.
Um diesen Fehler zu beheben, müssen Sie dafür sorgen, dass jede Schaltfläche eine richtig angegebene onClick
-Einstellung enthält.
Fehlerhaftes Karten-JSON-Snippet ansehen
Fehler: Das primaryButton
-Objekt hat ein onClick
-Feld mit einem falsch geschriebenen Array vom Typ „parameters“. Dadurch kann das Dialogfeld nicht geladen oder geöffnet werden.
. . . "fixedFooter": { "primaryButton": { "text": "Submit", "color": { "red": 0, "blue": 1, "green": 0 }, "onClick": { "action": { "function": "setLanguageType", "parrammetters": [ { "key": "languageType", "value": "C++" } ] } } }, "secondaryButton": { "text": "Cancel", "onClick": { "action": { "function": "reset" } } } } . . .
Korrektes JSON-Karten-Snippet ansehen
Behoben: Das primaryButton
-Objekt hat ein onClick
-Feld mit einem korrekt geschriebenen „parameters“-Array. Das Dialogfeld funktioniert also wie erwartet.
. . . "fixedFooter": { "primaryButton": { "text": "Submit", "color": { "red": 0, "blue": 1, "green": 0 }, "onClick": { "action": { "function": "setLanguageType", "parameters": [ { "key": "languageType", "value": "C++" } ] } } }, "secondaryButton": { "text": "Cancel", "onClick": { "action": { "function": "reset" } } } } . . .
Ursache: TextInput
enthält keine name
Wenn ein Dialogfeld ein TextInput
-Widget enthält, in dem das Feld name
nicht enthalten ist, verhält es sich nicht wie erwartet. Sie kann geschlossen, geöffnet, aber nicht geladen werden oder nicht geöffnet werden.
Um diesen Fehler zu beheben, achten Sie darauf, dass jedes TextInput
-Widget ein geeignetes name
-Feld enthält. Jedes name
-Feld auf der Karte muss eindeutig sein.
Fehlerhaftes Karten-JSON-Snippet ansehen
Fehler: Für das Objekt textInput
ist kein name
-Feld angegeben. Dies führt dazu, dass das Dialogfeld geschlossen, geladen oder geöffnet werden kann.
. . . { "textInput": { "label": "Name", "type": "SINGLE_LINE", } } . . .
Korrektes JSON-Karten-Snippet ansehen
Behoben: Für textInput
ist jetzt ein name
-Feld angegeben, sodass das Dialogfeld wie erwartet funktioniert.
. . . { "textInput": { "label": "Name", "type": "SINGLE_LINE", "name": "contactName" } } . . .
Aktionen zum Öffnen, Senden oder Abbrechen eines Dialogfelds schlagen mit einer asynchronen App-Architektur fehl
Wenn die Chat-App diese Fehlermeldung zurückgibt
Could not load dialog. Invalid response returned by bot.
bei der Arbeit mit
gedrückt wurde, kann das daran liegen,
verwendet eine asynchrone Architektur wie
Cloud Pub/Sub oder
Create Message API-Methode.
Das Öffnen, Senden oder Abbrechen eines Dialogfelds erfordert
eine synchrone Antwort von einer Chat-App mit einem
DialogEventType
Aus diesem Grund werden Dialogfelder von Apps nicht unterstützt
die mit einer asynchronen Architektur erstellt wurden.
Als Behelfslösung können Sie ein Kartennachricht anstelle eines Dialogfelds.
Andere Karten- und Dialogfeldfehler
Wenn der kartenbezogene Fehler in Ihrer App durch die auf dieser Seite beschriebenen Korrekturen nicht behoben werden kann, fragen Sie die Fehlerprotokolle der App ab. Abfragen der Protokolle können dabei helfen, Fehler im JSON-Karten- oder App-Code zu finden. Die Protokolle enthalten beschreibende Fehlermeldungen, die Ihnen bei der Fehlerbehebung helfen.
Weitere Informationen
Informationen zur Behebung von Fehlern in der Google Chat App finden Sie unter Fehlerbehebung bei der Google Chat App und Fehler in Chat-Apps beheben.