Probleme mit Karten und Dialogfeldern beheben

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

So 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 dieses 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 werden, 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">
</ph> Die Kopfzeile dieser Karte wird nicht angezeigt, weil ein Pflichtfeld (Titel) fehlt.
Abbildung 1: Der Header dieser Karte wird nicht angezeigt, da ein Pflichtfeld (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">
</ph> Die Kopfzeile dieser Karte wird nicht angezeigt, weil ein Pflichtfeld (Titel) fehlt.
Abbildung 2: Im Header dieser Karte wird keine Untertitel angezeigt, da ein Pflichtfeld (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.

<ph type="x-smartling-placeholder">
</ph> Die Kopfzeile dieser Karte wird nicht angezeigt, weil ein Pflichtfeld (Titel) fehlt.
Abbildung 3: Im Header dieser Karte wird keine Untertitel angezeigt, da ein Pflichtfeld (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:

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:

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.

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.