本指南將說明您可能會遇到的資訊卡相關常見錯誤,以及修正方法。
您可以使用 Card Builder 設計及預覽即時通訊應用程式的 JSON 資訊卡訊息:
開啟資訊卡建立工具資訊卡錯誤顯示方式
資訊卡錯誤資訊清單有幾種方式:
- 部分資訊卡 (例如小工具或元件) 無法顯示或以非預期的方式顯示。
- 系統不會顯示整張資訊卡。
- 對話方塊關閉、無法開啟或無法載入。
如果您遇到這種情況,表示應用程式的資訊卡發生錯誤。
參考資料:正常運作且未發生錯誤的卡片訊息和對話方塊
查看錯誤的卡片範例前,請先考慮這張有效資訊卡訊息與對話方塊。為說明每個範例錯誤及其修正方式,這張資訊卡的 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=9&hl=zh-tw)
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=9&hl=zh-tw)
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=9&hl=zh-tw)
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
物件的 onClick
欄位含有拼寫錯誤的「parameters」陣列,導致對話方塊無法載入或開啟。
. . . "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
物件的 onClick
欄位含有正確拼寫的「parameters」陣列,因此對話方塊可正常運作。
. . . "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 或
建立訊息 API 方法。
開啟、提交或取消對話方塊
同步回應來自 Chat 應用程式的
DialogEventType
。
因此,應用程式不支援對話方塊
以非同步架構建構而成。
您可以考慮使用 資訊卡訊息,而不是對話方塊。
其他資訊卡和對話方塊錯誤
如果本頁說明的修正方法無法解決應用程式體驗中的卡片相關錯誤,請查詢應用程式的錯誤記錄。查詢記錄檔可協助您找出卡片 JSON 或應用程式程式碼中的錯誤,且記錄檔會包含描述性的錯誤訊息,方便您進行修正。
相關主題
如需修正 Google Chat 應用程式錯誤的相關說明,請參閱「疑難排解及修正 Google Chat 應用程式」和「對 Chat 擴充應用程式進行偵錯」。