Risolvere i problemi e correggere schede e finestre di dialogo

Questa guida descrive gli errori comuni relativi alle schede che potresti riscontrare e come risolverli.

Utilizza Card Builder per progettare e visualizzare in anteprima le interfacce utente e di messaggistica per le app di chat:

Apri il generatore di schede

Come vengono visualizzati gli errori relativi alle carte

Gli errori della carta si manifestano in diversi modi:

  • Una parte di una scheda, come un widget o un componente, non viene visualizzata o viene visualizzata in modo imprevisto.
  • L'intera scheda non viene visualizzata.
  • Una finestra di dialogo si chiude, non si apre o non si carica.

Se riscontri un comportamento di questo tipo, significa che si è verificato un errore con la scheda della tua app.

Per riferimento: un messaggio e una finestra di dialogo della scheda funzionanti e privi di errori

Prima di esaminare gli esempi di schede errate, considera questo messaggio e questa finestra di dialogo della scheda funzionante. Per illustrare ogni errore di esempio e la relativa correzione, il JSON di questa scheda viene modificato introducendo errori.

Un messaggio della carta senza errori

Ecco il messaggio della scheda funzionante e privo di errori che descrive in dettaglio i dati di contatto e che include un'intestazione, sezioni e widget come testo decorato e pulsanti:

Una finestra di dialogo senza errori

Di seguito è riportata la finestra di dialogo funzionante e priva di errori che crea un contatto raccogliendo informazioni dagli utenti, con un piè di pagina e widget modificabili come input di testo e interruttori e pulsanti:

Errore: parte di una scheda non viene visualizzata

A volte le schede vengono visualizzate, ma una parte di una scheda che ti aspettavi di vedere non viene visualizzata. Le cause più probabili sono:

  • Manca un campo JSON obbligatorio.
  • Un campo JSON contiene un errore ortografico o è scritto in modo errato.

Causa: manca un campo JSON obbligatorio

In questo esempio di errore, manca un campo JSON obbligatorio, title. Di conseguenza, la scheda viene visualizzata, ma non le parti che dovrebbero apparire. Può essere difficile prevedere il rendering delle schede quando i campi obbligatori vengono omessi.

Per risolvere l'errore, aggiungi il campo JSON richiesto. In questo esempio, title.

Per sapere se un campo JSON è obbligatorio o meno, consulta la documentazione di riferimento di Cards v2. In questo esempio, fai riferimento alla descrizione del campo title su CardHeader.

Di seguito sono riportati due esempi:

Esempio 1: se specifichi subtitle ma ometti il parametro obbligatorio title, l'intera intestazione viene visualizzata vuota:

L'intestazione di questa scheda non viene visualizzata perché manca un campo obbligatorio, il titolo.
Figura 1: l'intestazione di questa scheda non viene visualizzata perché manca un campo obbligatorio, title.

Visualizza snippet JSON della scheda errata

Errore: manca un campo obbligatorio, title, in header.

    . . .
    "header": {

            "subtitle": "Software Engineer"
          }
    . . .

Visualizza lo snippet JSON della scheda corretto

Correzione: il campo obbligatorio title fa parte della specifica header.

    . . .
    "header": {
            "title": "Sasha",
            "subtitle": "Software Engineer"
          }
    . . .

Esempio 2: la specifica di subtitle, imageUrl, imageType e imageAltText, ma l'omissione del valore obbligatorio title fa sì che l'immagine venga visualizzata come previsto, ma non i sottotitoli codificati:

L'intestazione di questa scheda non viene visualizzata perché manca un campo obbligatorio, il titolo.
Figura 2: l'intestazione di questa scheda non mostra il sottotitolo perché manca un campo obbligatorio, title, ma l'immagine viene visualizzata come previsto.

Visualizza snippet JSON della scheda errata

Errore: manca un campo obbligatorio, title, in header.

    . . .
    "header": {

            "subtitle": "Software Engineer",
            "imageUrl":
            "https://developers.google.com/chat/images/quickstart-app-avatar.png",
            "imageType": "CIRCLE",
            "imageAltText": "Avatar for Sasha",
          }
    . . .

Visualizza lo snippet JSON della scheda corretto

Correzione: il campo obbligatorio title fa parte della specifica header.

    . . .
    "header": {
            "title": "Sasha",
            "subtitle": "Software Engineer",
            "imageUrl":
            "https://developers.google.com/chat/images/quickstart-app-avatar.png",
            "imageType": "CIRCLE",
            "imageAltText": "Avatar for Sasha",
          }
    . . .

Causa: JSON scritto o capitalizzato in modo errato

In questo esempio di errore, il JSON della scheda include tutti i campi necessari, ma un campo, imageUrl, è scritto in modo errato con la lettera maiuscola imageURL (R maiuscola L maiuscola), il che causa un errore: l'immagine a cui fa riferimento non viene visualizzata.

Per risolvere questo errore e altri simili, utilizza la formattazione JSON corretta. In questo caso, imageUrl è corretto. In caso di dubbi, controlla il codice JSON della scheda rispetto al documento di riferimento scheda.

L'intestazione di questa scheda non viene visualizzata perché manca un campo obbligatorio, il titolo.
Figura 3: l'intestazione di questa scheda non mostra il sottotitolo perché manca un campo obbligatorio, title, ma l'immagine viene visualizzata come previsto.

Visualizza snippet JSON della scheda errata

Errore: il campo imageURL è scritto in modo errato. Dovrebbe essere imageUrl.

    . . .
    "header": {
      "title": "Sasha",
      "subtitle": "Software Engineer",
      "imageURL":
      "https://developers.google.com/chat/images/quickstart-app-avatar.png",
      "imageType": "CIRCLE",
      "imageAltText": "Avatar for Sasha",
    }
    . . .

Visualizza lo snippet JSON della scheda corretto

Corretto: il campo imageUrl è scritto correttamente in maiuscolo.

    . . .
    "header": {
            "title": "Sasha",
            "subtitle": "Software Engineer",
            "imageUrl":
            "https://developers.google.com/chat/images/quickstart-app-avatar.png",
            "imageType": "CIRCLE",
            "imageAltText": "Avatar for Sasha",
          }
    . . .

Errore: una scheda intera non viene visualizzata

A volte la scheda non viene visualizzata. Le cause più probabili sono:

Causa: buttonList o cardFixedFooter specificato in modo errato

Se un messaggio o una finestra di dialogo della scheda include un widget ButtonList specificato in modo errato o un widget CardFixedFooter con pulsanti specificati in modo errato, l'intera scheda non viene visualizzata e non viene visualizzato nulla al suo posto. Le specifiche errate potrebbero includere campi mancanti, campi con errori ortografici o maiuscole o JSON strutturato in modo errato, ad esempio una virgola, virgoletta o parentesi graffa mancante.

Per correggere questo errore, controlla il JSON della scheda rispetto al documento di riferimento card. In particolare, confronta i widget ButtonList con la guida ai widget ButtonList.

Esempio:in una guida al widget ButtonList, il passaggio di un'azione onClick incompleta nel primo pulsante impedisce il rendering dell'intera scheda.

Visualizza snippet JSON della carta errata

Errore: l'oggetto onClick non ha campi specificati, quindi l'intera scheda non viene visualizzata.

    . . .
    {
      "buttonList": {
        "buttons": [
          {
            "text": "Share",
            "onClick": {


              }
            }
          },
          {
            "text": "Edit",
            "onClick": {
              "action": {
                "function": "goToView",
                "parameters": [
                  {
                    "key": "viewType",
                    "value": "EDIT",
                  }
                ],
              }
            }
          },
        ],
      },
    }
    . . .

Visualizza lo snippet JSON della scheda corretto

Corretto: l'oggetto onClick ora ha un campo openLink, quindi la scheda viene visualizzata come previsto.

    . . .
    {
      "buttonList": {
        "buttons": [
          {
            "text": "Share",
            "onClick": {
              "openLink": {
                "url": "https://example.com/share",
              }
            }
          },
          {
            "text": "Edit",
            "onClick": {
              "action": {
                "function": "goToView",
                "parameters": [
                  {
                    "key": "viewType",
                    "value": "EDIT",
                  }
                ],
              }
            }
          },
        ],
      },
    }
    . . .

Errore: una finestra di dialogo si chiude, si blocca o non si apre

Se una finestra di dialogo si chiude inaspettatamente, non viene caricata o non si apre, la causa probabile è un problema con l'interfaccia della scheda.

Ecco le cause più comuni:

Causa: CardFixedFooter non ha primaryButton

Nelle finestre di dialogo con un widget CardFixedFooter, è necessario specificare un primaryButton con testo e colore. Se ometti primaryButton o lo imposti in modo errato, l'intera finestra di dialogo non viene visualizzata.

Per correggere questo errore, assicurati che il widget CardFixedFooter includa un primaryButton specificato correttamente.

Visualizza snippet JSON della carta errata

Errore: l'oggetto fixedFooter non ha specificato il campo primaryButton, pertanto la finestra di dialogo non viene caricata o aperta.

    . . .
    "fixedFooter": {

        "onClick": {
          . . .
      },
      "secondaryButton": {
        . . .
        }
      }
    }
    . . .

Visualizza lo snippet JSON della scheda corretto

Corretto: ora fixedFooter ha un campo primaryButton specificato, quindi la finestra di dialogo funziona come previsto.

    . . .
    "fixedFooter": {
      "primaryButton": {
        "text": "Submit",
        "color": {
          "red": 0,
          "blue": 1,
          "green": 0
        },
        "onClick": {
          . . .
      },
      "secondaryButton": {
        . . .
        }
      }
    }
    . . .

Causa: impostazione onClick errata in FixedFooter

Nelle finestre di dialogo con un widget CardFixedFooter, la specifica dell'impostazione onClick su qualsiasi pulsante in modo errato o la sua omissione, causando la chiusura, il mancato caricamento o la mancata apertura della finestra di dialogo.

Per correggere questo errore, assicurati che ogni pulsante includa un'impostazione onClick specificata correttamente.

Visualizza snippet JSON della carta errata

Errore: l'oggetto primaryButton ha un campo onClick con un array "parameters" con errori ortografici, il che impedisce il caricamento o l'apertura della finestra di dialogo.

    . . .
    "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"
          }
        }
      }
    }
    . . .

Visualizza lo snippet JSON della scheda corretto

Corretto: l'oggetto primaryButton ha un campo onClick con un array "parameters" scritto correttamente, quindi la finestra di dialogo funziona come previsto.

    . . .
    "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"
          }
        }
      }
    }
    . . .

Causa: TextInput non ha name

Se una finestra di dialogo include un widget TextInput che esclude il campo name, la finestra di dialogo non si comporta come previsto. Potrebbe chiudersi, aprirsi ma non caricarsi o non aprirsi.

Per correggere questo errore, assicurati che ogni widget TextInput includa un campo name appropriato. Assicurati che ogni campo name nella scheda sia univoco.

Visualizza snippet JSON della carta errata

Errore: l'oggetto textInput non ha specificato il campo name, causando la chiusura, il mancato caricamento o la mancata apertura della finestra di dialogo.

    . . .
    {
      "textInput": {
        "label": "Name",
        "type": "SINGLE_LINE",

      }
    }
    . . .

Visualizza lo snippet JSON della scheda corretto

Corretto: ora textInput ha un campo name specificato, quindi la finestra di dialogo funziona come previsto.

    . . .
    {
      "textInput": {
        "label": "Name",
        "type": "SINGLE_LINE",
        "name": "contactName"
      }
    }
    . . .

Le azioni di apertura, invio o annullamento della finestra di dialogo non vanno a buon fine con un'architettura dell'app asincrona

Se la tua app Chat restituisce il messaggio di errore Could not load dialog. Invalid response returned by bot. mentre lavori con le finestre di dialogo, il problema potrebbe essere che la tua app utilizza un'architettura asincrona, come Cloud Pub/Sub o il metodo API Crea messaggio.

L'apertura, l'invio o l'annullamento di una finestra di dialogo richiede una risposta sincrona da un'app di chat con un DialogEventType. Di conseguenza, le finestre di dialogo non sono supportate dalle app create con un'architettura asincrona.

Come soluzione alternativa, valuta la possibilità di utilizzare un messaggio della scheda anziché una finestra di dialogo.

Altri errori relativi a schede e finestre di dialogo

Se le correzioni descritte in questa pagina non risolvono l'errore relativo alla carta riscontrato dall'app, interroga i log degli errori dell'app. L'esecuzione di query sui log può aiutarti a trovare errori nel codice JSON della scheda o nel codice dell'app. I log includono messaggi di errore descrittivi per aiutarti a risolverli.

Per assistenza nella correzione degli errori dell'app Google Chat, vedi Risolvere i problemi e correggere l'app Google Chat e Eseguire il debug delle app di chat.