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 與 license key 不匹配，請修改其中的任意一個，使其匹配
Invalid Key: No matched Package Name	Bundle ID 與 license key 不匹配，請修改其中的任意一個，使其匹配
Invalid Key: License does not apply to current variant	使用了企業包的 SDK 但非企業版的 license key，或使用了非企業包的 SDk 但使用了企業包的 license key
Invalid Key: License for an old version does not apply	license 版本太老，應重新創建新的license
Invalid Key: Invalid format	license 格式錯誤，比如沒有複製全
Invalid Key: Server verification failed	license 已刪除或無設備使用權限，如果是頭顯使用，請聯繫商務添加權限
License does not apply to eyewear	license 不能在頭顯上使用，請更換 xr license
License is expired	license 已過期

此外，您應當注意試用版本的 License 會有一些限制，使用付費版本的 EasyAR Sense 和付費的 EasyAR Mega 服務可以解決這個問題。如果您已經在使用付費版的 EasyAR Sense，可以忽略或直接從 sample 中刪除相關文字。

相機畫面異常

在開發或者測試 EasyAR Mega 應用的過程中，如出現黑屏、閃退、相機無畫面等異常問題，請按照以下步驟系統排查和收集信息。

1. 嘗試自行解決

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

  

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

• 多數情況中，錯誤信息都有自說明，如果屏幕信息或日誌已經說明了出錯原因，可以根據具體原因去解決。如： cameraDevice.openWithPreferredType fail（需要檢查相機是否可用）。

• 如果提示“不支持”（如設備不支持 ARCore、或者其他特性），屬於正常限制，無需進一步排查。

2. 無法自行解決

   請先根據已有信息嘗試自行解決，如果無法自行解決，爲幫助 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 開發，插件版本 >= 4003
• Unity 開發，插件版本 4.7 - 4002
• 小程序開發
• 其它 Mega Studio 使用場景

在您使用的 block 節點的編輯器工具上，點擊下圖中的 Diagnosis Info 按鈕，導出 Mega Block 診斷信息。Mega Block 診斷信息 中僅包含 Mega Block 以及定位庫信息，不包含其他敏感信息。

您導出的文件格式應當是 Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json。

錄製 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 中復現問題

若已經完成上述 4 項檢查，仍然無法解決您的問題，您可以在 EasyAR Sense Unity Plugin 按照下面流程提供完整的信息，以供 EasyAR 技術人員分析並解決您的問題。

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

   

2. 在 提問中需要提供以下信息

   • 選擇出問題的運行環境，只支持選擇單個環境
   • 複製設備信息，在 EasyAR Session 中將 DiagnosticsController.DumpSession 設置爲 Log，複製一幀的輸出並填寫結果到下方
   • 選擇您出問題時所用的所有 EasyAR 功能，支持多選
   • 確定已經完成上述 4 項檢查，建議在提問時描述如何在 Sample 中復現的問題
   • 點擊右上角的複製功能 剛打開提問窗口，下方的信息顯示不全，需要您在選擇使用的環境和功能後纔會顯示。

3. 點擊下方的前往 EasyAR 問答 將複製的信息反饋給 EasyAR 官方，或者直接反饋給 EasyAR 工作人員