이 가이드에서는 일반적으로 발생할 수 있는 카드 관련 오류와 해결 방법을 설명합니다.
카드 빌더로 카드를 디자인하고 미리 봅니다.
카드 빌더 열기카드 오류가 표시되는 방식
카드 오류는 다음과 같이 표시됩니다.
- 위젯이나 구성요소와 같은 카드의 일부가 표시되지 않거나 예기치 않은 방식으로 렌더링됩니다.
- 전체 카드가 표시되지 않습니다.
- 대화상자가 닫히거나 열리지 않거나 로드되지 않습니다.
이러한 동작이 발생하면 앱 카드에 오류가 있는 것입니다.
참고: 오류 없이 작동하는 카드 메시지 및 대화상자
잘못된 카드 예시를 검토하기 전에 먼저 작동하는 카드 메시지와 대화상자를 살펴보세요. 각 오류 예와 수정 방법을 설명하기 위해 이 카드의 JSON은 오류를 도입하여 수정됩니다.
오류가 없는 카드 메시지
다음은 헤더, 섹션, 위젯(예: 장식된 텍스트, 버튼)이 포함된 연락처 정보를 자세히 설명하는 오류 없이 작동하는 카드 메시지입니다.
오류가 없는 대화상자
다음은 사용자로부터 정보를 수집하고, 바닥글, 텍스트 입력 및 스위치, 버튼과 같은 수정 가능한 위젯을 표시하여 오류 없이 작동하는 대화상자입니다.
오류: 카드의 일부가 표시되지 않음
카드가 렌더링되지만 예상했던 카드의 일부가 표시되지 않을 때가 있습니다. 가능한 원인은 다음과 같습니다.
- 필수 JSON 필드가 누락되었습니다.
- JSON 필드의 철자가 잘못되었거나 대문자로 표시됩니다.
원인: 필수 JSON 필드 누락
이 오류 예시에서는 필수 JSON 필드인 title
가 누락되었습니다. 따라서 카드는 렌더링되지만 표시되어야 하는 카드 일부는 렌더링되지 않습니다. 필수 필드가 누락되면 카드가 어떻게 렌더링되는지 예측하기 어려울 수 있습니다.
이 오류를 수정하려면 필수 JSON 필드(이 예시에서는 title
)를 추가합니다.
JSON 필드가 필요한지 알아보려면 카드 v2 참조 문서를 확인하세요. 이 예시에서는 CardHeader
의 title
필드 설명을 참고하세요.
다음은 두 가지 예입니다.
예 1: subtitle
를 지정했지만 필수 title
를 생략하면 전체 헤더가 공백으로 표시됩니다.
![필수 입력란인 제목이 누락되어 카드의 헤더가 표시되지 않습니다.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-1.png?authuser=6&hl=ko)
title
가 누락되어 이 카드의 헤더가 표시되지 않습니다.잘못된 카드 JSON 스니펫 보기
오류: header
에 필수 입력란 title
이(가) 누락되었습니다.
. . . "header": { "subtitle": "Software Engineer" } . . .
올바른 카드 JSON 스니펫 보기
수정됨: 필수 필드 title
가 header
사양의 일부입니다.
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer" } . . .
예시 2: subtitle
, imageUrl
, imageType
, imageAltText
를 지정하고 필수 title
를 생략하면 이미지가 예상대로 렌더링되지만 부제목은 렌더링되지 않습니다.
![필수 입력란인 제목이 누락되어 카드의 헤더가 표시되지 않습니다.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-2.png?authuser=6&hl=ko)
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을 카드 참조 문서와 비교해 보세요.
![필수 입력란인 제목이 누락되어 카드의 헤더가 표시되지 않습니다.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-imageURL-instead-of-imageUrl.png?authuser=6&hl=ko)
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 앱 문제 해결 및 수정하기 및 채팅 앱 디버그를 참고하세요.