In diesem Leitfaden werden häufige Kartenfehler beschrieben, die auftreten können, und wie Sie sie beheben können.
Mit dem Card Builder können Sie Nachrichten und Benutzeroberflächen für Chat-Apps entwerfen und in der Vorschau ansehen:
Karten-Tool öffnenDarstellung von Kartenfehlern
Kartenfehler können sich auf verschiedene Weise äußern:
- Ein Teil einer Karte, z. B. ein Widget oder eine Komponente, wird nicht angezeigt oder auf unerwartete Weise gerendert.
- Die Karte wird nicht vollständig angezeigt.
- Ein Dialogfeld wird geschlossen, öffnet sich nicht oder wird nicht geladen.
Wenn ein solches Verhalten auftritt, liegt ein Fehler mit der Karte Ihrer App vor.
Zur Veranschaulichung: Eine funktionierende, fehlerfreie Kartenmitteilung und ein Dialogfeld
Bevor Sie sich Beispiele für fehlerhafte Karten ansehen, sehen Sie sich diese Nachricht und diesen Dialog für eine funktionierende Karte an. Um die einzelnen Beispielfehler und ihre Behebung zu veranschaulichen, wird das JSON dieser Karte durch das Einfügen von Fehlern geändert.
Eine fehlerfreie Kartennachricht
Hier sehen Sie die funktionierende, fehlerfreie Kartennachricht mit Kontaktdaten, die einen Titel, Abschnitte und Widgets wie Text mit Rahmen und Schaltflächen enthält:
Ein fehlerfreies Dialogfeld
Hier sehen Sie das funktionierende, fehlerfreie Dialogfeld, mit dem ein Kontakt erstellt wird, indem Informationen von Nutzern erfasst werden. Es enthält eine Fußzeile und bearbeitbare Widgets wie Textfelder, Schalter und Schaltflächen:
Fehler: Ein Teil einer Karte wird nicht angezeigt
Manchmal werden Karten gerendert, aber ein Teil einer Karte, der eigentlich angezeigt werden sollte, ist nicht zu sehen. Die wahrscheinlichen Ursachen sind:
- Ein Pflicht-JSON-Feld fehlt.
- Ein JSON-Feld enthält Rechtschreibfehler oder die Groß- und Kleinschreibung ist falsch.
Ursache: Ein erforderliches JSON-Feld fehlt
In diesem Beispielfehler fehlt das erforderliche JSON-Feld title
. Daher wird die Karte gerendert, aber Teile der Karte, die eigentlich angezeigt werden sollten, werden nicht angezeigt. Es kann schwierig sein vorherzusagen, wie Karten gerendert werden, wenn Pflichtfelder fehlen.
Fügen Sie zum Beheben dieses Fehlers das erforderliche JSON-Feld hinzu, in diesem Beispiel title
.
Ob ein JSON-Feld erforderlich ist, erfahren Sie in der Referenzdokumentation für Google Maps Platform Cards v2. In diesem Beispiel finden Sie die Beschreibung des Felds title
auf CardHeader
.
Hier sind zwei Beispiele:
Beispiel 1: Wenn Sie subtitle
angeben, aber die erforderliche title
auslassen, wird der gesamte Header leer angezeigt:
JSON-Snippet für fehlerhafte Karte ansehen
Fehler: In header
fehlt das Pflichtfeld title
.
. . . "header": { "subtitle": "Software Engineer" } . . .
Korrektes JSON-Snippet für Karte ansehen
Behoben: Das Pflichtfeld title
ist Teil der header
-Spezifikation.
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer" } . . .
Beispiel 2: Wenn du subtitle
, imageUrl
, imageType
und imageAltText
angibst, aber das erforderliche title
auslässt, wird das Bild wie erwartet gerendert, aber nicht der Untertitel:
JSON-Snippet für fehlerhafte 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-Snippet für Karte ansehen
Behoben: 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: Falsch geschriebene oder falsch großgeschriebene JSON-Datei
In diesem Beispielfehler enthält die Karten-JSON-Datei alle erforderlichen Felder, aber ein Feld, imageUrl
, ist falsch großgeschrieben als imageURL
(R
L
). Dies führt zu einem Fehler: Das darauf verweisende Bild wird nicht gerendert.
Verwenden Sie die richtige JSON-Formatierung, um diesen und ähnliche Fehler zu beheben. In diesem Fall ist imageUrl
richtig. Im Zweifelsfall solltest du die JSON-Datei der Karte mit dem Referenzdokument Karte vergleichen.
JSON-Snippet für fehlerhafte Karte ansehen
Fehler: Das Feld imageURL
ist falsch großgeschrieben. 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-Snippet für Karte ansehen
Korrigiert: Das Feld imageUrl
wird jetzt korrekt 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: Eine ganze Karte wird nicht angezeigt
Manchmal wird die Karte selbst nicht angezeigt. Das kann folgende Ursachen haben:
- Ein
ButtonList
-Widget ist falsch angegeben. - Für ein
CardFixedFooter
-Widget wurde eine Schaltfläche falsch angegeben.
Ursache: Falsch angegebene 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 wird nichts angezeigt. Zu den falschen Spezifikationen können fehlende Felder, falsch geschriebene oder falsch formatierte Felder oder nicht ordnungsgemäß strukturierte JSON-Dateien gehören, z. B. ein fehlendes Komma, Anführungszeichen oder geschweifte Klammer.
Um diesen Fehler zu beheben, vergleiche die JSON-Datei der Karte mit dem Referenzdokument Karte. Vergleichen Sie insbesondere alle ButtonList
-Widgets mit dem ButtonList
-Widget-Leitfaden.
Beispiel:In einem ButtonList
-Widget-Leitfaden wird durch das Übergeben einer unvollständigen onClick
-Aktion in der ersten Schaltfläche verhindert, dass die gesamte Karte gerendert wird.
Falsche Karte – JSON-Snippet ansehen
Fehler: Für das onClick
-Objekt sind keine Felder angegeben. Daher wird die gesamte Karte nicht angezeigt.
. . . { "buttonList": { "buttons": [ { "text": "Share", "onClick": { } } }, { "text": "Edit", "onClick": { "action": { "function": "goToView", "parameters": [ { "key": "viewType", "value": "EDIT", } ], } } }, ], }, } . . .
Richtiges JSON-Snippet für Karte ansehen
Behoben: Das onClick
-Objekt hat jetzt 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, hängt oder öffnet sich nicht
Wenn sich ein Dialogfeld unerwartet schließt, nicht geladen wird oder sich nicht öffnet, liegt wahrscheinlich ein Problem mit der Kartenoberfläche vor.
Das kann folgende Gründe haben:
- Das
CardFixedFooter
-Widget hat keinprimaryButton
. - Eine Schaltfläche im
CardFixedFooter
-Widget hat keineonClick
-Aktion oder dieonClick
-Aktion ist falsch angegeben. - In einem
TextInput
-Widget fehlt das Feldname
.
Ursache: CardFixedFooter
hat keine primaryButton
In Dialogfeldern mit einem CardFixedFooter
-Widget muss ein primaryButton
mit Text und Farbe angegeben werden. Wenn Sie das primaryButton
weglassen oder falsch festlegen, wird das gesamte Dialogfeld nicht angezeigt.
Achten Sie darauf, dass das CardFixedFooter
-Widget eine korrekt angegebene primaryButton
enthält, um diesen Fehler zu beheben.
Falsche Karte – JSON-Snippet ansehen
Fehler: Für das fixedFooter
-Objekt ist kein primaryButton
-Feld angegeben. Das Dialogfeld kann daher nicht geladen oder geöffnet werden.
. . . "fixedFooter": { "onClick": { . . . }, "secondaryButton": { . . . } } } . . .
Richtiges JSON-Snippet für Karte 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
Wenn in Dialogfeldern mit einem CardFixedFooter
-Widget die onClick
-Einstellung für eine Schaltfläche falsch angegeben oder weggelassen wird, wird das Dialogfeld geschlossen, kann nicht geladen oder nicht geöffnet werden.
Um diesen Fehler zu beheben, muss für jede Schaltfläche eine korrekt angegebene onClick
-Einstellung vorhanden sein.
Falsche Karte – JSON-Snippet ansehen
Fehler: Das primaryButton
-Objekt hat ein onClick
-Feld mit einem falsch geschriebenen „parameters“-Array, wodurch das Dialogfeld nicht geladen oder geöffnet werden kann.
. . . "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" } } } } . . .
Richtiges JSON-Snippet für Karte ansehen
Behoben: Das primaryButton
-Objekt hat ein onClick
-Feld mit einem korrekt geschriebenen „parameters“-Array, sodass das Dialogfeld wie erwartet funktioniert.
. . . "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
hat keine name
Wenn ein Dialog ein TextInput
-Widget enthält, das das Feld name
ausschließt, funktioniert das Dialogfeld nicht wie erwartet. Möglicherweise wird die Seite geschlossen, geöffnet, aber nicht geladen oder gar nicht geöffnet.
Achten Sie darauf, dass jedes TextInput
-Widget ein entsprechendes name
-Feld enthält, um diesen Fehler zu beheben. Achten Sie darauf, dass jedes name
-Feld auf der Karte eindeutig ist.
Falsche Karte – JSON-Snippet ansehen
Fehler: Für das textInput
-Objekt ist kein name
-Feld angegeben. Das Dialogfeld wird geschlossen, kann nicht geladen oder nicht geöffnet werden.
. . . { "textInput": { "label": "Name", "type": "SINGLE_LINE", } } . . .
Richtiges JSON-Snippet für Karte 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 von Dialogfeldern schlagen bei einer asynchronen App-Architektur fehl
Wenn Ihre Chat-App beim Arbeiten mit Dialogen die Fehlermeldung Could not load dialog. Invalid response returned by bot.
zurückgibt, kann das daran liegen, dass Ihre App eine asynchrone Architektur verwendet, z. B. Cloud Pub/Sub oder die API-Methode Create Message.
Zum Öffnen, Senden oder Abbrechen eines Dialogfelds ist eine synchrone Antwort von einer Chat-App mit einem DialogEventType
erforderlich.
Daher werden Dialoge von Apps, die mit einer asynchronen Architektur erstellt wurden, nicht unterstützt.
Als Behelfslösung können Sie stattdessen eine Kartennachricht verwenden.
Andere Karten- und Dialogfeldfehler
Wenn der auf dieser Seite beschriebene Fehler nicht behoben wird, rufen Sie die Fehlerprotokolle der App ab. Durch Abfragen der Protokolle können Sie Fehler im JSON-Code der Karte oder im App-Code finden. Die Protokolle enthalten beschreibende Fehlermeldungen, die Ihnen bei der Behebung helfen.
Weitere Informationen
Informationen zur Behebung von Google Chat-App-Fehlern finden Sie unter Fehlerbehebung bei der Google Chat App und Google Chat-Apps debuggen.