카드 및 대화상자 문제 해결 및 해결하기

이 가이드에서는 발생할 수 있는 일반적인 카드 관련 오류와 해결 방법을 설명합니다.

---

카드 작성 도구를 사용하여 Chat 앱의 메시지 및 사용자 인터페이스를 디자인하고 미리 볼 수 있습니다.

카드 작성 도구 열기

---

카드 오류가 표시되는 방식

카드 오류는 다음과 같은 여러 가지 방식으로 나타납니다.

• 위젯이나 구성요소와 같은 카드의 일부가 예상치 못하게 표시되거나 렌더링되지 않습니다.
• 카드 전체가 표시되지 않습니다.
• 대화상자가 닫히거나 열리지 않거나 로드되지 않습니다.

이와 같은 동작이 발생하면 앱의 카드에 오류가 있는 것입니다.

참고용: 오류가 없는 작동하는 카드 메시지 및 대화상자

잘못된 카드 예시를 살펴보기 전에 먼저 작동하는 카드 메시지와 대화상자를 살펴보세요. 각 오류 예시와 해결 방법을 보여주기 위해 이 카드의 JSON이 오류를 도입하여 수정되었습니다.

오류가 없는 카드 메시지

다음은 헤더, 섹션, 꾸며진 텍스트 및 버튼과 같은 위젯이 포함된 연락처 정보를 자세히 설명하는 오류가 없는 작동하는 카드 메시지입니다.

오류가 없는 대화상자

다음은 사용자로부터 정보를 수집하여 연락처를 만드는 오류가 없는 대화상자입니다. 바닥글, 텍스트 입력과 스위치와 같은 수정 가능한 위젯, 버튼이 포함되어 있습니다.

오류: 카드 일부가 표시되지 않음

카드가 렌더링되지만 예상했던 카드의 일부가 표시되지 않는 경우가 있습니다. 그럴 수 있는 원인은 다음과 같습니다.

• 필수 JSON 필드가 누락되었습니다.
• JSON 필드의 맞춤법이 잘못되었거나 대소문자가 잘못되었습니다.

원인: 필수 JSON 필드가 누락됨

이 오류 예시에서 필수 JSON 필드 title가 누락되었습니다. 그 결과 카드가 렌더링되지만 표시되어야 하는 카드의 일부가 표시되지 않습니다. 필수 입력란을 생략하면 카드가 렌더링되는 방식을 예측하기 어려울 수 있습니다.

이 오류를 수정하려면 필수 JSON 필드(이 예에서는 title)를 추가합니다.

JSON 필드가 필요한지 여부는 Cards v2 참조 문서를 참고하세요. 이 예에서는 CardHeader의 title 필드에 관한 설명을 참고하세요.

다음은 두 가지 예입니다.

예 1: subtitle를 지정했지만 필수 title를 생략하면 전체 헤더가 비어 있게 됩니다.

그림 1: 필수 입력란인 title가 누락되어 이 카드의 헤더가 표시되지 않습니다.

잘못된 카드 JSON 스니펫 보기

오류: header에 필수 입력란 title이 누락되었습니다.

    . . .
    "header": {

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

올바른 카드 JSON 스니펫 보기

Fixed(해결됨): 필수 입력란 title이 header 사양의 일부입니다.

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

예 2: subtitle, imageUrl, imageType, imageAltText를 지정했지만 필수 title를 생략하면 이미지는 예상대로 렌더링되지만 자막은 렌더링되지 않습니다.

그림 2: 필수 입력란인 title가 누락되어 이 카드의 헤더에 자막이 표시되지 않지만 이미지는 예상대로 렌더링됩니다.

잘못된 카드 JSON 스니펫 보기

오류: header에 필수 입력란 title이 누락되었습니다.

    . . .
    "header": {

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

올바른 카드 JSON 스니펫 보기

Fixed(해결됨): 필수 입력란 title이 header 사양의 일부입니다.

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

원인: JSON의 철자가 잘못되었거나 대문자가 잘못 적용됨

이 오류 예시에서 카드 JSON에는 모든 필드가 포함되어 있지만 imageUrl 필드 하나가 imageURL (대문자 R 대문자 L)로 잘못 대문자로 표시되어 오류가 발생합니다. 가리키는 이미지가 렌더링되지 않습니다.

이 오류와 유사한 오류를 수정하려면 올바른 JSON 형식을 사용하세요. 이 경우 imageUrl가 올바릅니다. 확실하지 않은 경우 카드 JSON을 카드 참조 문서와 대조합니다.

그림 3: 필수 입력란인 title가 누락되어 이 카드의 헤더에 자막이 표시되지 않지만 이미지는 예상대로 렌더링됩니다.

잘못된 카드 JSON 스니펫 보기

오류: imageURL 필드의 대문자가 잘못되었습니다. imageUrl이어야 합니다.

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

올바른 카드 JSON 스니펫 보기

수정됨: imageUrl 필드가 올바르게 대문자로 표시됩니다.

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

오류: 전체 카드가 표시되지 않음

카드 자체가 표시되지 않는 경우도 있습니다. 그럴 수 있는 원인은 다음과 같습니다.

• ButtonList 위젯이 잘못 지정되었습니다.
• CardFixedFooter 위젯에 잘못 지정된 버튼이 있습니다.

원인: buttonList 또는 cardFixedFooter가 잘못 지정됨

카드 메시지 또는 대화상자에 잘못 지정된 ButtonList 위젯 또는 잘못 지정된 버튼이 있는 CardFixedFooter 위젯이 포함된 경우 전체 카드가 표시되지 않고 그 자리에 아무것도 표시되지 않습니다. 잘못된 사양에는 누락된 필드, 잘못된 철자 또는 대문자로 표시된 필드, 잘못된 구조의 JSON(예: 누락된 쉼표, 따옴표 또는 중괄호)이 포함될 수 있습니다.

이 오류를 수정하려면 카드 JSON을 카드 참조 문서와 비교하세요. 특히 ButtonList 위젯을 ButtonList 위젯 가이드와 비교하세요.

예: ButtonList 위젯 가이드에서 첫 번째 버튼에 불완전한 onClick 작업을 전달하면 전체 카드가 렌더링되지 않습니다.

잘못된 카드 JSON 스니펫 보기

오류: onClick 객체에 지정된 필드가 없으므로 전체 카드가 표시되지 않습니다.

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


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

올바른 카드 JSON 스니펫 보기

해결됨: 이제 onClick 객체에 openLink 필드가 있으므로 카드가 예상대로 표시됩니다.

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

오류: 대화상자가 닫히거나 중단되거나 열리지 않음

대화상자가 예기치 않게 닫히거나 로드되지 않거나 열리지 않는 경우 카드 인터페이스에 문제가 있을 가능성이 큽니다.

가장 일반적인 이유는 다음과 같습니다.

• CardFixedFooter 위젯에는 primaryButton가 없습니다.
• CardFixedFooter 위젯의 버튼에 onClick 작업이 없거나 onClick 작업이 잘못 지정되었습니다.
• TextInput 위젯에 name 필드가 누락되었습니다.

원인: CardFixedFooter에 primaryButton가 없음

CardFixedFooter 위젯이 있는 대화상자에서는 텍스트와 색상이 모두 포함된 primaryButton를 지정해야 합니다. primaryButton를 생략하거나 잘못 설정하면 전체 대화상자가 표시되지 않습니다.

이 오류를 수정하려면 CardFixedFooter 위젯에 올바르게 지정된 primaryButton가 포함되어 있는지 확인합니다.

잘못된 카드 JSON 스니펫 보기

오류: fixedFooter 객체에 지정된 primaryButton 필드가 없어 대화상자가 로드 또는 열리지 않습니다.

    . . .
    "fixedFooter": {

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

올바른 카드 JSON 스니펫 보기

해결됨: 이제 fixedFooter에 primaryButton 필드가 지정되어 대화상자가 예상대로 작동합니다.

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

원인: FixedFooter의 onClick 설정이 잘못됨

CardFixedFooter 위젯이 있는 대화상자에서 버튼의 onClick 설정을 잘못 지정하거나 생략하여 대화상자가 닫히거나, 로드되지 않거나, 열리지 않습니다.

이 오류를 수정하려면 각 버튼에 올바르게 지정된 onClick 설정이 포함되어 있는지 확인합니다.

잘못된 카드 JSON 스니펫 보기

오류: primaryButton 객체에 철자가 잘못된 `parameters` 배열이 있는 onClick 필드가 있어 대화상자가 로드 또는 열리지 않습니다.

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

올바른 카드 JSON 스니펫 보기

수정됨: primaryButton 객체에 맞춤법이 올바른 `parameters` 배열이 있는 onClick 필드가 있으므로 대화상자가 예상대로 작동합니다.

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

원인: TextInput에 name가 없음

대화상자에 name 필드를 제외하는 TextInput 위젯이 포함된 경우 대화상자가 예상대로 작동하지 않습니다. 닫히거나 열리지만 로드되지 않거나 열리지 않을 수 있습니다.

이 오류를 수정하려면 각 TextInput 위젯에 적절한 name 필드가 포함되어 있는지 확인합니다. 카드의 각 name 필드가 고유해야 합니다.

잘못된 카드 JSON 스니펫 보기

오류: textInput 객체에 지정된 name 필드가 없어 대화상자가 닫히거나, 로드되지 않거나, 열리지 않습니다.

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

      }
    }
    . . .
    

올바른 카드 JSON 스니펫 보기

해결됨: 이제 textInput에 name 필드가 지정되어 대화상자가 예상대로 작동합니다.

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

비동기 앱 아키텍처에서 대화상자 열기, 제출 또는 취소 작업이 실패함

Chat 앱이 대화상자를 사용하는 동안 오류 메시지 Could not load dialog. Invalid response returned by bot.를 반환하는 경우 앱이 Cloud Pub/Sub 또는 Create Message API 메서드와 같은 비동기 아키텍처를 사용하기 때문일 수 있습니다.

대화상자를 열거나, 제출하거나, 취소하려면 Chat 앱에서 DialogEventType를 사용하여 동기식 응답을 받아야 합니다. 따라서 비동기 아키텍처로 빌드된 앱에서는 대화상자가 지원되지 않습니다.

이 문제를 해결하려면 대화상자 대신 카드 메시지를 사용하는 것이 좋습니다.

기타 카드 및 대화상자 오류

이 페이지에 설명된 수정사항으로 앱에서 발생하는 카드 관련 오류가 해결되지 않으면 앱의 오류 로그를 쿼리하세요. 로그를 쿼리하면 카드 JSON 또는 앱 코드에서 오류를 찾는 데 도움이 되며, 로그에는 오류를 수정하는 데 도움이 되는 설명적인 오류 메시지가 포함되어 있습니다.

관련 주제

Google Chat 앱 오류를 해결하는 데 도움이 필요한 경우 Google Chat 앱 문제 해결 및 수정 및 Chat 앱 디버그를 참고하세요.