이 가이드에서는 일반적으로 발생할 수 있는 카드 관련 오류와 해결 방법을 설명합니다.
카드 빌더로 카드를 디자인하고 미리 봅니다.
카드 빌더 열기카드 오류가 표시되는 방식
카드 오류는 다음과 같이 표시됩니다.
- 위젯이나 구성요소와 같은 카드의 일부가 표시되지 않거나 예기치 않은 방식으로 렌더링됩니다.
- 전체 카드가 표시되지 않습니다.
- 대화상자가 닫히거나 열리지 않거나 로드되지 않습니다.
이러한 동작이 발생하면 앱 카드에 오류가 있는 것입니다.
참고: 오류 없이 작동하는 카드 메시지 및 대화상자
잘못된 카드 예시를 검토하기 전에 먼저 작동하는 카드 메시지와 대화상자를 살펴보세요. 각 오류 예와 수정 방법을 설명하기 위해 이 카드의 JSON은 오류를 도입하여 수정됩니다.
오류가 없는 카드 메시지
다음은 헤더, 섹션, 위젯(예: 장식된 텍스트, 버튼)이 포함된 연락처 정보를 자세히 설명하는 오류 없이 작동하는 카드 메시지입니다.
오류가 없는 대화상자
다음은 사용자로부터 정보를 수집하고, 바닥글, 텍스트 입력 및 스위치, 버튼과 같은 수정 가능한 위젯을 표시하여 오류 없이 작동하는 대화상자입니다.
오류: 카드의 일부가 표시되지 않음
카드가 렌더링되지만 예상했던 카드의 일부가 표시되지 않을 때가 있습니다. 가능한 원인은 다음과 같습니다.
- 필수 JSON 필드가 누락되었습니다.
- JSON 필드의 철자가 잘못되었거나 대문자로 표시됩니다.
원인: 필수 JSON 필드 누락
이 오류 예시에서는 필수 JSON 필드인 title가 누락되었습니다. 따라서 카드는 렌더링되지만 표시되어야 하는 카드 일부는 렌더링되지 않습니다. 필수 필드가 누락되면 카드가 어떻게 렌더링되는지 예측하기 어려울 수 있습니다.
이 오류를 수정하려면 필수 JSON 필드(이 예시에서는 title)를 추가합니다.
JSON 필드가 필요한지 알아보려면 카드 v2 참조 문서를 확인하세요. 이 예시에서는 CardHeader의 title 필드 설명을 참고하세요.
다음은 두 가지 예입니다.
예 1: subtitle를 지정했지만 필수 title를 생략하면 전체 헤더가 공백으로 표시됩니다.
title가 누락되어 이 카드의 헤더가 표시되지 않습니다.잘못된 카드 JSON 스니펫 보기
오류: header에 필수 입력란 title이(가) 누락되었습니다.
. . .
"header": {
"subtitle": "Software Engineer"
}
. . .
올바른 카드 JSON 스니펫 보기
수정됨: 필수 필드 title가 header 사양의 일부입니다.
. . .
"header": {
"title": "Sasha",
"subtitle": "Software Engineer"
}
. . .
예시 2: subtitle, imageUrl, imageType, imageAltText를 지정하고 필수 title를 생략하면 이미지가 예상대로 렌더링되지만 부제목은 렌더링되지 않습니다.
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 스니펫 보기
수정됨: 필수 필드 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을 카드 참조 문서와 비교해 보세요.
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"
}
}
. . .
비동기 앱 아키텍처에서 열기, 제출 또는 취소 작업이 실패함
대화상자를 사용하는 동안 채팅 앱이 Could not load dialog. Invalid response returned by bot. 오류 메시지를 반환하는 경우 앱에서 Cloud Pub/Sub 또는 Create Message API 메서드와 같은 비동기 아키텍처를 사용하기 때문일 수 있습니다.
대화상자를 열거나 제출하거나 취소하려면 채팅 앱에서 DialogEventType를 사용하여 동기 응답을 받아야 합니다.
따라서 비동기 아키텍처로 빌드된 앱에서는 대화상자가 지원되지 않습니다.
이 문제를 해결하려면 대화상자 대신 카드 메시지를 사용해 보세요.
기타 카드 및 대화상자 오류
이 페이지에 설명된 해결 방법으로 앱에서 발생하는 카드 관련 오류가 해결되지 않으면 앱의 오류 로그를 쿼리하세요. 로그를 쿼리하면 카드 JSON 또는 앱 코드에서 오류를 찾는 데 도움이 될 수 있으며 로그에는 오류 해결에 도움이 되는 자세한 오류 메시지가 포함됩니다.
관련 주제
Google Chat 앱 오류를 해결하는 데 도움이 필요하면 Google Chat 앱 문제 해결 및 수정하기 및 채팅 앱 디버그를 참고하세요.