Resolver problemas e corrigir cards e caixas de diálogo

Este guia descreve erros comuns relacionados a cards e como corrigi-los.

Use o Card Builder para criar e visualizar interfaces do usuário e mensagens de apps de chat:

Abrir o criador de cards

Como os erros de card aparecem

Os erros de cartão se manifestam de várias maneiras:

  • Parte de um card, como um widget ou componente, não aparece ou é renderizado de maneira inesperada.
  • O card inteiro não aparece.
  • Uma caixa de diálogo fecha, não abre ou não carrega.

Se você encontrar um comportamento como esse, significa que há um erro no card do app.

Para referência: uma mensagem e uma caixa de diálogo de cartão funcional e sem erros

Antes de examinar exemplos de cards incorretos, considere primeiro esta mensagem e caixa de diálogo de cards em funcionamento. Para ilustrar cada exemplo de erro e a correção dele, o JSON deste card foi modificado com a introdução de erros.

Uma mensagem de cartão sem erros

Esta é a mensagem de card funcional e sem erros, que detalha as informações de contato e inclui um cabeçalho, seções e widgets, como texto e botões decorados:

Uma caixa de diálogo sem erros

Confira a caixa de diálogo funcional e sem erros que cria um contato coletando informações dos usuários, com um rodapé e widgets editáveis, como entrada de texto e botões:

Erro: parte de um card não aparece

Às vezes, os cards são renderizados, mas parte de um card que você esperava não aparece. As causas prováveis são:

  • Um campo JSON obrigatório está ausente.
  • Um campo JSON está com erros de ortografia ou letras maiúsculas incorretas.

Causa: falta um campo JSON obrigatório

Neste exemplo de erro, um campo JSON obrigatório, title, está ausente. Como resultado, o card é renderizado, mas partes dele que deveriam aparecer não são. Pode ser difícil prever como os cards são renderizados quando os campos obrigatórios são omitidos.

Para corrigir esse erro, adicione o campo JSON necessário. Neste exemplo, title.

Para saber se um campo JSON é obrigatório, consulte a documentação de referência do Cards v2. Neste exemplo, consulte a descrição do campo title em CardHeader.

Veja dois exemplos:

Exemplo 1: especificar subtitle, mas omitir o title obrigatório faz com que o cabeçalho inteiro apareça em branco:

O cabeçalho do card não aparece porque um campo obrigatório, o título, está ausente.
Figura 1: o cabeçalho do card não aparece porque um campo obrigatório, title, está ausente.

Conferir o snippet JSON de cartão incorreto

Erro: um campo obrigatório, title, está ausente em header.

    . . .
    "header": {

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

Conferir o snippet JSON correto do cartão

Corrigido: o campo obrigatório, title, faz parte da especificação header.

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

Exemplo 2: especificar subtitle, imageUrl, imageType e imageAltText, mas omitir o title necessário faz com que a imagem seja renderizada como esperado, mas não a legenda:

O cabeçalho do card não aparece porque um campo obrigatório, o título, está ausente.
Figura 2: o cabeçalho deste card não mostra o subtítulo porque um campo obrigatório, title, está ausente, mas a imagem é renderizada como esperado.

Conferir o snippet JSON de cartão incorreto

Erro: um campo obrigatório, title, está ausente em header.

    . . .
    "header": {

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

Conferir o snippet JSON correto do cartão

Corrigido: o campo obrigatório, title, faz parte da especificação 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 com ortografia ou letras maiúsculas incorretas

Neste exemplo de erro, o JSON do card inclui todos os campos necessários, mas um campo, imageUrl, está com letras maiúsculas incorretamente como imageURL (letra maiúscula R letra maiúscula L), o que causa um erro: a imagem apontada não é renderizada.

Para corrigir esse erro e outros semelhantes, use a formatação JSON correta. Nesse caso, imageUrl está correto. Em caso de dúvida, verifique o JSON do cartão no documento de referência do cartão.

O cabeçalho do card não aparece porque um campo obrigatório, o título, está ausente.
Figura 3: o cabeçalho do card não mostra o subtítulo porque um campo obrigatório, title, está ausente, mas a imagem é renderizada como esperado.

Conferir o snippet JSON de cartão incorreto

Erro: o campo imageURL está com letras maiúsculas incorretas. Deve ser imageUrl.

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

Conferir o snippet JSON correto do cartão

Correção: o campo imageUrl está com letras maiúsculas corretamente.

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

Erro: um card inteiro não aparece

Às vezes, o card não aparece. As causas mais prováveis são:

Causa: buttonList ou cardFixedFooter especificados incorretamente

Se uma mensagem ou caixa de diálogo de card incluir um widget ButtonList ou um widget CardFixedFooter com botões especificados incorretamente, o card inteiro não será exibido e nada aparecerá no lugar dele. Especificações incorretas podem incluir campos ausentes, campos com ortografia incorreta ou campos com letras maiúsculas, ou JSON estruturado incorretamente, como uma vírgula, aspas ou chaves ausentes.

Para corrigir esse erro, verifique o JSON do cartão no documento de referência card. Em particular, compare os widgets ButtonList com o guia de widgets ButtonList.

Exemplo:em um guia de widgets ButtonList, transmitir uma ação onClick incompleta no primeiro botão impede a renderização do card inteiro.

Conferir o snippet JSON de cartão com erro

Erro: o objeto onClick não tem campos especificados, então o cartão inteiro não aparece.

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


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

Conferir o snippet JSON correto do card

Correção: o objeto onClick agora tem um campo openLink, então o card aparece como esperado.

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

Erro: uma caixa de diálogo fecha, trava ou não abre.

Se uma caixa de diálogo fechar inesperadamente, não carregar ou não abrir, provavelmente há um problema com a interface do cartão.

Estes são os motivos mais comuns:

Causa: CardFixedFooter não tem primaryButton

Em caixas de diálogo com um widget CardFixedFooter, é necessário especificar um primaryButton com texto e cor. Omitir o primaryButton ou defini-lo incorretamente impede a exibição de toda a caixa de diálogo.

Para corrigir esse erro, verifique se o widget CardFixedFooter inclui um primaryButton especificado corretamente.

Conferir o snippet JSON de cartão com erro

Erro: o objeto fixedFooter não tem um campo primaryButton especificado, fazendo com que a caixa de diálogo não seja carregada ou aberta.

    . . .
    "fixedFooter": {

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

Conferir o snippet JSON correto do card

Correção: o fixedFooter agora tem um campo primaryButton especificado, para que a caixa de diálogo funcione conforme o esperado.

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

Causa: configuração onClick incorreta em FixedFooter

Em caixas de diálogo com um widget CardFixedFooter, especificar a configuração onClick em qualquer botão incorretamente ou omiti-la, fazendo com que a caixa de diálogo seja fechada, não seja carregada ou não seja aberta.

Para corrigir esse erro, verifique se cada botão inclui uma configuração onClick especificada corretamente.

Conferir o snippet JSON de cartão com erro

Erro: o objeto primaryButton tem um campo onClick com uma matriz "parameters" com erro de ortografia, fazendo com que a caixa de diálogo não carregue nem abra.

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

Conferir o snippet JSON correto do card

Correção: o objeto primaryButton tem um campo onClick com uma matriz "parameters" com ortografia correta, para que a caixa de diálogo funcione conforme o esperado.

    . . .
    "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 não tem name

Se uma caixa de diálogo incluir um widget TextInput que exclui o campo name, a caixa de diálogo não vai se comportar como esperado. Ele pode fechar, abrir, mas não carregar ou não abrir.

Para corrigir esse erro, verifique se cada widget TextInput inclui um campo name adequado. Verifique se cada campo name no card é exclusivo.

Conferir o snippet JSON de cartão com erro

Erro: o objeto textInput não tem um campo name especificado, fazendo com que a caixa de diálogo seja fechada, não seja carregada ou não seja aberta.

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

      }
    }
    . . .

Conferir o snippet JSON correto do card

Correção: o textInput agora tem um campo name especificado, para que a caixa de diálogo funcione conforme o esperado.

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

As ações de abrir, enviar ou cancelar caixas de diálogo falham com uma arquitetura de app assíncrona.

Se o app de chat retornar a mensagem de erro Could not load dialog. Invalid response returned by bot. ao trabalhar com caixas de diálogo, talvez seja porque o app usa uma arquitetura assíncrona, como o Cloud Pub/Sub ou o método da API Create Message.

Abrir, enviar ou cancelar uma caixa de diálogo exige uma resposta síncrona de um app de chat com um DialogEventType. Portanto, as caixas de diálogo não são compatíveis com apps criados com uma arquitetura assíncrona.

Como solução alternativa, use uma mensagem de cartão em vez de uma caixa de diálogo.

Outros erros de card e caixa de diálogo

Se as correções descritas nesta página não resolverem o erro relacionado ao cartão do seu app, consulte os registros de erros do app. Consultar os registros pode ajudar a encontrar erros no JSON do cartão ou no código do app. Além disso, os registros incluem mensagens de erro descritivas para ajudar a corrigi-los.

Para receber ajuda para corrigir erros do app do Google Chat, consulte Resolver problemas e corrigir o app do Google Chat e Depurar apps do Chat.