Probleme mit Karten und Dialogfeldern beheben

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 öffnen

Darstellung 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:

Der Header dieser Karte wird nicht angezeigt, da das Pflichtfeld „Titel“ fehlt.
Abbildung 1: Die Überschrift dieser Karte wird nicht angezeigt, da das Pflichtfeld title fehlt.

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:

Der Header dieser Karte wird nicht angezeigt, da das Pflichtfeld „Titel“ fehlt.
Abbildung 2: In der Überschrift dieser Karte wird der Untertitel nicht angezeigt, da ein Pflichtfeld (title) fehlt. Das Bild wird jedoch wie erwartet gerendert.

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.

Der Header dieser Karte wird nicht angezeigt, da das Pflichtfeld „Titel“ fehlt.
Abbildung 3: In der Überschrift dieser Karte wird der Untertitel nicht angezeigt, da ein Pflichtfeld (title) fehlt. Das Bild wird jedoch wie erwartet gerendert.

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:

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:

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.

Informationen zur Behebung von Google Chat-App-Fehlern finden Sie unter Fehlerbehebung bei der Google Chat App und Google Chat-Apps debuggen.