Table of Contents

疑難排解：內容未顯示/啟用

在使用影像雲識別過程中，可能遇到虛擬內容無法顯示或啟用的問題。本文將提供系統性排查方法。需要提醒的是，大部分情況下影像雲識別失敗的原因與本地識別失敗是完全一致的，可參考平面影像追蹤的 疑難排解 章節。此處僅補充雲識別特有的問題與解決方案。

常見原因與排查方法

網路連線問題

現象：識別請求發送後無回應，或傳回錯誤碼。
排查方法：

  • 檢查設備是否連網（Wi-Fi/4G/5G），嘗試開啟網頁驗證。
  • 檢查應用是否開啟了連網權限。
  • 在程式碼中捕捉網路錯誤日誌。
  • 在瀏覽器測試 CRS API 連通性（參考：健康檢查 | GET /ping）。

改善建議：

  • 應用內增加網路狀態檢測，弱網時提供提示。
  • 設定請求逾時後重試或降級至本地追蹤。

服務設定錯誤

現象：識別請求被拒絕，傳回 Unauthorized 或 Invalid Key。
排查方法：

  • 檢查程式碼中填入的 CRS API Key 和 Secret 是否正確。
  • 檢查程式碼中填入的 Client-end URL 沒有填錯（如誤填成 Server-end URL）。
  • 確認 License Key 已啟用且未過期（在 EasyAR 官網帳戶中心查看）。

改善建議：

  • 使用 CRS 影像庫中的複製按鈕複製您的相關服務設定，確保填寫正確。

目標庫/應用設定錯誤

現象：某個目標影像過去識別沒有問題，但現在識別請求失敗。
排查方法：

  • 透過 CRS API 取得目標狀態，確認目標影像是「已啟用」狀態（"active":"1"）。
  • 檢查目標 ID 是否與程式碼中完全一致（區分大小寫）。

改善建議：

  • 雲端影像庫有更新/變動時，確保應用的特定目標總是啟用的。
  • 仔細的程式碼核查。

混合模式下的本地載入失敗

現象：雲端識別成功，但本地追蹤未啟動，內容未顯示。
排查方法：

  • 確認本地 ImageTarget 載入時未拋出例外（查看日誌）。
  • 驗證 ImageTracker 是否已啟用。

改善建議：

  • 使用 try-catch 包裹本地載入邏輯，捕捉例外並重試。
  • 確保虛擬內容是 ImageTarget 的子物件，且未被停用。

總結與最佳實踐

雲識別內容未顯示問題主要集中在網路、服務設定、目標狀態三方面，混合模式還需關注本地載入環節。建議按以下順序優先排查：

  1. 檢查網路連線，確認 CRS 服務連通性；
  2. 檢查 License、API Key/Secret、Client-end URL 等服務設定。
  3. 檢查 CRS 影像庫中目標影像的狀態，確保影像庫與應用中的目標 ID 一致；

若問題複雜，可啟用 EasyAR 偵錯日誌或聯繫技術支援。