Table of Contents

UI 消息

EasyAR Sense Unity Plugin 運行時有三類訊息。

  • 執行異常，包含 Sense Error、Session Error、Error、Warning
  • Session Dump
  • EasyAR Mega 開發特殊異常

您可以根據需要調整前兩類訊息的輸出方式。可以通過 session 上的 DiagnosticsController 元件在編輯器中設定，或是使用 DiagnosticsController.MessageOutput 介面在腳本中設定。

diagnostics ui messages

提示

在 4000 版本中，若場景由舊版本插件建立，開啟場景時 DiagnosticsController 會被自動新增到 session 中。部分 Unity 版本中可能不會自動新增，在這些 Unity 版本中，DiagnosticsController 會在執行時自動以預設值建立。

執行異常

插件執行時有時會收到內部元件發現的一些問題，以訊息形式出現在系統中。這些訊息有些可能是無法繼續使用的嚴重故障，有些可能是故意觸發的，有些可能是裝置不受支援等等，按嚴重級別從高到低分為如下幾類：

  • SenseError：EasyAR Sense 錯誤，通常與 EasyAR Sense license 有關。
  • SessionError：ARSession 錯誤，通常與裝置不支援一些功能或錯誤的設定有關。
  • Error：其它錯誤資訊
  • Warning：警告資訊

由於 Unity 開發的特殊性，我們預設會將這些訊息顯示在 UI 上，以輔助開發。

可以在編輯器或腳本中控制這些訊息如何展示，可以選擇的輸出模式如下：

  • UIAndLog：輸出到UI和日誌。在頭顯上顯示在眼前5米處。
  • Log：輸出到系統日誌。
提示
  • 建議在開發測試階段使用預設設定 UIAndLog。
  • 建議在發佈時將選項改成 Log， 也可以保留 UIAndLog，但這些UI訊息通常對終端使用者是不友善的。
  • 建議在執行前 判斷 session 可用性和裝置支援 並對不支援的裝置進行合理提示。

Sense Error

Sense Error 是一類特殊的錯誤，出現錯誤時 EasyAR 功能無法繼續使用。常見原因：

  • License 未正確設定或校驗失敗。該錯誤可以通過使用正確的 license 重新初始化來恢復。
  • 部分裝置（包括 AR Foundation、AR Engine 等所有使用自訂相機的裝置或各種頭顯）上使用試用產品（個人版 license、試用版 XR license 或試用版 Mega 服務等）超過固定的有限時間。該錯誤無法恢復。

Session Error

Session Error 是當前 ARSession 無法繼續工作的錯誤。修改設定並重新執行 ARSession 可能可以解決這些錯誤。這些錯誤一般是由於您的設定錯誤、啟動流程中拋出了異常導致組裝中斷、裝置不受當前 ARSession 設定支援或是執行過程中 ARSession 元件遺失等導致的。

常見情況有：

  • Session 組裝錯誤：比如裝置不受支援或支援裝置的 Frame Source 沒有正確設定在 ARSession 中等。
  • Session 啟動錯誤：雲服務設定資訊錯誤導致建立雲服務功能出錯，或設定資訊未填寫（包括 Mega 服務、雲端辨識服務、SpatialMap 服務）等。
  • Session 執行中錯誤：ARSession 元件被外部銷燬，URP 環境下未正確設定 RendererFeature 等。

通常來說，設定錯誤以及啟動流程中的異常導致組裝中斷都應該在開發過程中避免。裝置不支援的情況主要出現在需要運動跟蹤能力的功能上，需要參考 運動跟蹤與 EasyAR 功能 了解哪些功能需要注意裝置支援，並在開發階段選擇合適的裝置進行偵錯。

Session Dump

SessionDump 訊息展示的是插件執行時收集的 ARSession 的執行狀態，包括各個元件的一些關鍵狀態。這些狀態資訊對了解 EasyAR 的執行以及分析問題有很大幫助。

可以在編輯器或腳本中控制這些狀態如何展示，可以選擇的輸出模式如下：

  • UI：顯示在 UI 並每幀更新。在頭顯上，顯示在眼前5米處。
  • Log：輸出到系統日誌，由於每幀都輸出，對執行效能是有影響的，建議在開發或測試時使用。
  • None：不輸出。
提示
  • 建議在開發測試階段使用預設設定 UI，上面顯示的資訊是與 EasyAR 工作人員進行溝通所必不可少的。
  • 建議在正式上線後再修改為 None，並保留開啟 UI 的軟體開關，或通過其它系統進行資料收集。在向 EasyAR 回饋問題時， EasyAR 會向您或您的使用者索取這些資訊，以判斷應用執行狀態。
  • 在絕大多數情況下，應用上線後執行出問題，應用端還是需要首先進行問題排查和分析，在排除應用問題並取得足夠資訊後回饋的問題才能較好解決。日誌收集和分析的第三方 SDK 和平台比較多，建議上線前使用。若您沒有使用這些平台的經驗或資源，保留開啟 UI 的開關（比如使用隱藏開關）讓使用者回饋看到的資訊將是比較簡單的。

EasyAR Mega 開發特殊異常

Mega 開發中，還有一類無法控制的警告資訊，這類資訊會在滿足特定設定條件時顯示在 UI 上，開發者無法直接關閉。

建議關注資訊本身，文字上寫明了出現的原因和設定方法。開發者需要了解不同設定對不同使用方式的要求並根據開發進展合理選擇。

這類資訊是故意展示的，因為在特定使用條件下，這些功能用來輔助內容流程開發，但同時無法取得合理的執行結果，注意不要帶著資訊上線。

相關主題