Table of Contents

Mega 定位失敗排查指南

Mega 基於先進的視覺定位演算法，透過雲端 Mega Block 檢索、視覺特徵匹配解算實現高精度定位。因此實際使用過程中，因配置錯誤、環境變化或網路波動等多種原因，可能會導致定位失敗。

本文檔旨在幫助您快速判斷定位狀態，區分「正常等待」與「異常錯誤」，並根據配置、環境、服務三大類因素進行快速診斷。

定位流程

需要您在目標區域內採集建圖數據並構建 Mega Block，將已經重建的 Mega Block 添加至定位庫中，並確定定位庫可用。

在已經構建 Mega Block 的覆蓋區域內，且環境光線良好、特徵豐富，網路正常，通常數秒內即可定位成功。定位成功後會返回當前設備在 Mega Block 中的位置以及姿態。

判斷定位狀態

  • 若您使用 Mega Toolbox 驗證定位結果，可以直接查看定位狀態

    診斷資訊

  • 若您是 Unity 開發者，出現無法定位時，可以在螢幕上查看定位返回的具體資訊 MegaTrackerLocalizationStatus，如螢幕上沒有該資訊，需要打開診斷資訊。

    診斷資訊

MegaTrackerLocalizationStatus 可能的值

Constant Value Description
UnknownError 0 未知錯誤
Found 1 定位到 Block
NotFound 2 沒有定位到 Block
RequestTimeout 3 請求逾時(超過 1 分鐘)
RequestIntervalTooLow 4 請求間隔過短
QpsLimitExceeded 5 QPS 超過限制
WakingUp 6 服務正在喚醒中
MissingSpotVersionId 7 缺少 SpotVersionId，可能是沒有設定
ApiTokenExpired 8 API Token 過期

出現以上異常的解決辦法：

  • 請求逾時：查看並修復網路情況，如有必要可以調高請求逾時時間 MegaRequestTimeParameters.Timeout，但網路情況不好也會對追蹤效果產生影響，因此需要盡量解決網路問題
  • 請求間隔過短：降低請求間隔
  • 連線或傳輸失敗：查看並修復網路情況
  • QPS 超過限制：聯繫 EasyAR 商務同學，進行 QPS 擴容
  • 服務正在喚醒中：系統正在喚醒中，請等待一段時間再進行重試
  • 缺少 SpotVersionId：請配置 SpotVersionId
  • API Token 過期：請在 EasyAR 管理後台重新生成 API Token

UnknownError 常見有兩種情況

  • 連線或傳輸失敗
  • 服務返回異常

對於UnknownError，可以通過 MegaLocalizationResponse.ErrorMessage 獲取詳細資訊

常見錯誤分類排查

根據定位返回的狀態及現象，常見問題可分為以下三類：配置問題、環境因素、服務本身。

配置问题

此類問題通常發生在開發接入階段，表現為服務完全無法啟動。

License 相關

若您在開發或測試過程中，於日誌或畫面提示出現 License、 Invalid Key 等問題，可能原因包含：AppID/BundleID 不符、License 過期、套餐權限不符等，請參照下表檢查您的 License 設定。

錯誤 解決方法
Invalid Key: No matched Bundle ID Bundle ID 與授權金鑰不匹配，請修改任一項使其相符
Invalid Key: No matched Package Name Bundle ID 與授權金鑰不匹配，請修改任一項使其相符
Invalid Key: License does not apply to current variant 使用了企業版的 SDK 卻非企業版的授權金鑰，或使用非企業版 SDK 卻配置企業版授權金鑰
Invalid Key: License for an old version does not apply 授權版本過舊，應重新建立新授權
Invalid Key: Invalid format 授權格式錯誤（例如未完整複製內容）
Invalid Key: Server verification failed 授權已被刪除或無裝置使用權限。若需於頭顯裝置使用，請聯繫商務人員開通權限
License does not apply to eyewear 此授權無法於頭顯裝置使用，請更換為 xr license
License is expired 授權已過期

此外，請留意試用版 License 存在功能限制，使用付費版 EasyAR Sense 及付費的 EasyAR Mega 服務可解決此問題。若您已使用付費版 EasyAR Sense，可忽略或直接從 sample 中移除相關提示文字。

相機畫面異常

在開發或測試 EasyAR Mega 應用時，如出現黑屏、閃退、相機無畫面等異常問題，請按照以下步驟系統性排查並收集資訊。

  1. 嘗試自行解決

  • 如您使用 Unity 開發測試，請確保已在 AR Session (EasyAR) -> Inspector 中勾選 Diagnostics Controller (Script) 以開啟診斷資訊。

    診斷資訊

  • 查看螢幕或日誌顯示的內容，檢查 UI 上是否有明確的文字提示。

  • 多數情況下，錯誤資訊具有自說明性，若螢幕資訊或日誌已說明出錯原因，可根據具體原因解決。例如：cameraDevice.openWithPreferredType fail（需檢查相機是否可用）。

  • 若提示「不支援」（如裝置不支援 ARCore 或其他特性），屬正常限制，無需進一步排查。

  1. 無法自行解決

    請先根據已有資訊嘗試自行解決，若無法解決，為協助 EasyAR 工作人員快速定位問題，請務必提供纖細、可復現的技術資訊，切勿僅描述如「黑屏」現象。建議回饋內容包括：

  • 完整日誌：Unity 或 Sense 日誌
  • 螢幕截圖或錄屏：黑屏時的完整畫面，如有診斷資訊請確保可見並截圖
  • 詳細裝置資訊：裝置型號（如 iPhone 15、HUAWEI P40）、系統版本（如 iOS 17.1、Android 14）、EasyAR Sense 版本、EasyAR Sense Unity Plugin 版本、Unity 版本等

不在現場運行，持續 NotFound

開發者在辦公室使用模擬器或錄屏測試，但始終無法定位。可能的原因是 MegaLocationInputMode 模式設置為 Onsite，但並非在現場運行。需要根據 Mega 位置輸入模式，在開發過程中選擇正確的模式：

Constant Value Description
Onsite 0 在現場使用的情況的輸入模式，位置數據通常從設備獲取並輸入到Mega，通常由FrameFilter內部處理
Simulator 1 遠程使用的情況的輸入模式，位置數據需要模擬成現場數據並通過對應接口輸入Mega（可選）
FramePlayer 2 在使用 FramePlayer 時的輸入模式。這個模式是只讀的

环境因素引起

此類問題表現為服務正常，但是定位持續返回 NotFound。

對著白牆、地面持續 NotFound

當相機畫面中是大面積白牆、玻璃或純色地面，狀態會持續返回 NotFound。

原因：視覺定位依賴紋理特徵。弱紋理區域無法提取特徵點。

解決方法：這是正常現象，需要將相機移向有豐富紋理的區域進行啟動。

在現場且紋理豐富，但持續 NotFound

人在現場，對著紋理豐富的區域，但長時間無法成功定位。

可能原因：

  • 場景變化：現場環境（如裝修、海報更換、光照劇烈變化）與建圖時的場景差異過大。
  • 採集未覆蓋：使用者站立的位置超出了當初採集建圖的覆蓋範圍。

解決方法：

  • 移動到當初採集的路線區域嘗試。
  • 若場景已發生永久性巨大變化，需要重新採集並更新 Block。

服務本身引起

刚添加 block，持续 wakingUp

刚配置完定位庫或剛啟動定位庫時，服務狀態顯示 WakingUp 或長時間 NotFound。由於 Mega 服務具備冷啟動機制，首次加載需從冷存儲喚醒。保持網絡通暢，等待 10~30 秒重試即可。

服務返回異常

Https status Status code 原因
200 21 QPS 超出限制
200 1040 x 參數、庫或者地圖數據不正確，見具體消息描述
200 4000 x 算法級別報錯，見具體描述
401 - 認證失敗，見具體消息描述
404 - URL 中的路徑輸入不正確
50x - 伺服器程式報錯

出現服務異常的解決方法：

  • 出現 QPS 限制：聯繫 EasyAR 商務同學，進行 QPS 擴容
  • 出現認證失敗：根據具體消息描述解決，常見問題有設備時間與標準時間偏差過大、API Key沒有CLS權限等
  • 其他情況：請反饋給 EasyAR 工作人員解決

問題回饋

若經過上述排查仍無法解決問題，請按以下步驟收集資訊並回饋給 EasyAR 技術支援團隊。

導出 Mega 定位服務 資訊

在 Unity 的 Mega Studio 中登入您的帳號，選擇您定位異常的定位庫後，找到下圖中的Mega 定位服務導出按鈕。您導出的檔案格式應為MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json。Mega 定位服務中僅包含 MegaBlock 以及定位庫資訊，不包含其他敏感資訊。

導出 Mega 定位服務資訊

錄製 EIF 檔案

若在手機測試時遇到問題，請使用Toolbox 錄製手機 EIF 檔案

若在眼鏡測試時遇到問題，請使用Toolbox 錄製眼鏡 EIF 檔案

若您是在自己的應用中遇到問題，可以使用您的應用錄製 EIF 檔案

使用微信小程序時，可使用小程序錄製 EIF 檔案

使用手機、眼鏡等設備錄製問題現象

在 AR 領域，文字描述通常很難傳達準確的資訊，每個人的理解可能會天差地別。與此同時，運行時的螢幕錄影是非常有用的資訊，可以讓您和 EasyAR 工作人員建立共同的理解。可以使用手機、眼鏡等設備自帶功能或者借助第三方軟體進行錄製。需要注意的是，在錄屏過程中一般會對運行效果產生影響，追蹤效果和性能都可能會受到影響。

附註

錄屏之前，建議在運行時參考對應的 Sample，將一些必要的 Debug 資訊顯示在螢幕上。在提供錄屏的同時，您應當提供錄屏期間對應的EIF數據。

Unity 開發問題回饋

若您在使用 Unity 開發過程中遇到異常問題，應依序完成以下 4 項檢查：

  1. 已嘗試最新版本的 EasyAR Sense Unity Plugin。新版本通常包含 bug修復及新功能，建議先升級至最新版本測試
  2. 已閱讀 EasyAR 開發文件 及 Mega 指南，文件中通常會說明特殊情況
  3. 已查閱系統及 Unity 日誌，建議提問時提供完整日誌
  4. 已嘗試在空的 Unity 專案中，透過 Sample 重現問題

若完成上述檢查仍無法解決問題，請在 EasyAR Sense Unity Plugin 依以下流程提供完整資訊，供 EasyAR 技術人員分析：

  1. 在 Unity -> EasyAR -> Sense 中選擇提問
    提問

  2. 在提問中需提供以下資訊：

    • 選擇出問題的執行環境（僅支援單一環境）
    • 複製裝置資訊：於 EasyAR Session 中將 DiagnosticsController.DumpSession 設為 Log，複製一幀的輸出結果並填寫至下方
      dump session
    • 選擇所有使用到的 EasyAR 功能（可多選）
    • 確認已完成上述 4 項檢查，建議描述如何在 Sample 中重現問題
    • 點擊右上角複製按鈕
      匯出 Unity 開發資訊
      剛開啟提問視窗時下方資訊顯示不全，需先選擇環境及功能後才會完整顯示。
      選擇環境和功能

  3. 點擊下方前往 EasyAR 問答 提交複製的資訊，或直接回饋給 EasyAR 工作人員
    問題回饋