Panduan pemecahan masalah kegagalan lokalisasi Mega

Mega menggunakan algoritma lokalisasi visual canggih untuk mencapai lokalisasi presisi tinggi melalui pengambilan Mega Block berbasis cloud dan pencocokan fitur visual. Dalam penggunaan praktis, berbagai faktor seperti kesalahan konfigurasi, perubahan lingkungan, atau fluktuasi jaringan dapat menyebabkan kegagalan lokalisasi.

Dokumen ini bertujuan membantu Anda dengan cepat menilai status lokalisasi, membedakan antara "menunggu normal" dan "kesalahan abnormal", serta melakukan diagnosis cepat berdasarkan tiga kategori utama: konfigurasi, lingkungan, dan layanan.

Alur pelokalan

Anda perlu mengumpulkan data pemetaan di area target dan membangun Mega Block, menambahkan Mega Block yang telah direkonstruksi ke dalam perpustakaan pelokalan, serta memastikan perpustakaan pelokalan dapat digunakan.

Di area yang telah dicakup oleh Mega Block yang dibangun, dengan pencahayaan lingkungan yang baik, fitur yang kaya, dan jaringan normal, pelokalan biasanya berhasil dalam hitungan detik. Setelah pelokalan berhasil, posisi dan orientasi perangkat saat ini di dalam Mega Block akan dikembalikan.

Menentukan status pelokalan

• Jika Anda menggunakan Mega Toolbox untuk memverifikasi hasil pelokalan, Anda dapat langsung melihat status pelokalan

  

• Jika Anda adalah pengembang Unity, saat mengalami kegagalan pelokalan, Anda dapat melihat informasi spesifik yang dikembalikan MegaTrackerLocalizationStatus di layar. Jika informasi ini tidak muncul di layar, Anda perlu mengaktifkan informasi diagnostik.

  

Nilai yang mungkin dari MegaTrackerLocalizationStatus

Konstanta	Nilai	Deskripsi
UnknownError	0	Kesalahan tidak dikenal
Found	1	Berhasil melokalisasi Block
NotFound	2	Gagal menemukan Block
RequestTimeout	3	Permintaan waktu habis (melebihi 1 menit)
RequestIntervalTooLow	4	Interval permintaan terlalu pendek
QpsLimitExceeded	5	QPS melebihi batas
WakingUp	6	Layanan sedang dalam proses bangun
MissingSpotVersionId	7	SpotVersionId tidak ada, kemungkinan belum diatur
ApiTokenExpired	8	API Token telah kedaluwarsa

Solusi untuk pengecualian di atas:

• Permintaan waktu habis: Periksa dan perbaiki kondisi jaringan. Jika perlu, Anda dapat menaikkan batas waktu permintaan MegaRequestTimeParameters.Timeout. Namun, kondisi jaringan yang buruk juga akan memengaruhi efek pelacakan, jadi masalah jaringan perlu diselesaikan sebaik mungkin.
• Interval permintaan terlalu pendek: Kurangi interval permintaan.
• Koneksi atau transmisi gagal: Periksa dan perbaiki kondisi jaringan.
• QPS melebihi batas: Hubungi tim bisnis EasyAR untuk meningkatkan kapasitas QPS.
• Layanan sedang dalam proses bangun: Sistem sedang bangun, harap tunggu beberapa saat sebelum mencoba kembali.
• SpotVersionId tidak ada: Harap konfigurasikan SpotVersionId.
• API Token kedaluwarsa: Harap buat ulang API Token di dashboard EasyAR.

UnknownError umumnya memiliki dua situasi:

• Koneksi atau transmisi gagal
• Layanan mengembalikan pengecualian

Untuk UnknownError, detail informasi dapat diperoleh melalui MegaLocalizationResponse.ErrorMessage.

Penyelesaian masalah klasifikasi kesalahan umum

Berdasarkan status dan gejala yang ditampilkan setelah penentuan lokasi, masalah umum dapat dibagi menjadi tiga kategori berikut: masalah konfigurasi, faktor lingkungan, dan layanan itu sendiri.

Masalah konfigurasi

Jenis masalah ini biasanya terjadi pada tahap pengembangan integrasi, yang ditandai dengan layanan yang sama sekali tidak dapat dimulai.

License terkait

Jika Anda menemukan masalah License, Invalid Key, dll. dalam log atau petunjuk layar selama pengembangan atau pengujian, kemungkinan penyebabnya: AppID/BundleID tidak cocok, License kedaluwarsa, ketidaksesuaian paket, dll. Silakan periksa pengaturan License Anda dengan tabel berikut.

Kesalahan	Solusi
Invalid Key: No matched Bundle ID	Bundle ID tidak cocok dengan license key, silakan ubah salah satunya agar cocok
Invalid Key: No matched Package Name	Bundle ID tidak cocok dengan license key, silakan ubah salah satunya agar cocok
Invalid Key: License does not apply to current variant	Menggunakan SDK paket perusahaan dengan license key non-enterprise, atau sebaliknya
Invalid Key: License for an old version does not apply	License versi terlalu lama, buat license baru
Invalid Key: Invalid format	Format license salah, misalnya tidak disalin sepenuhnya
Invalid Key: Server verification failed	License dihapus atau tidak memiliki izin penggunaan perangkat. Jika digunakan di headset, hubungi tim bisnis untuk menambahkan izin
License does not apply to eyewear	License tidak dapat digunakan di headset, gunakan license xr
License is expired	License telah kedaluwarsa

Selain itu, perhatikan bahwa License versi percobaan memiliki beberapa batasan. Menggunakan layanan EasyAR Sense versi berbayar dan EasyAR Mega berbayar dapat menyelesaikan masalah ini. Jika Anda sudah menggunakan EasyAR Sense versi berbayar, abaikan atau hapus teks terkait langsung dari sampel.

Kamera tampilan tidak normal

Selama pengembangan atau pengujian aplikasi EasyAR Mega, jika muncul masalah tidak normal seperti layar hitam, crash, tidak ada tampilan kamera, silakan ikuti langkah-langkah berikut untuk memeriksa secara sistematis dan mengumpulkan informasi.

1. Coba selesaikan sendiri

• Jika Anda menggunakan Unity untuk pengembangan dan pengujian, pastikan Anda telah mencentang Diagnostics Controller (Script) di AR Session (EasyAR) -> Inspector untuk mengaktifkan informasi diagnostik.
• Periksa konten yang ditampilkan di layar atau log, periksa apakah ada petunjuk teks yang jelas di UI.
• Dalam sebagian besar kasus, pesan kesalahan bersifat self-explanatory. Jika informasi di layar atau log sudah menjelaskan penyebab kesalahan, Anda dapat menyelesaikannya berdasarkan penyebab spesifik tersebut. Contoh: cameraDevice.openWithPreferredType fail (perlu memeriksa apakah kamera tersedia/berfungsi).
• Jika muncul pesan "tidak didukung" (misalnya perangkat tidak mendukung ARCore, atau fitur lainnya), ini merupakan batasan normal dan tidak perlu pemeriksaan lebih lanjut.

2. Tidak dapat diselesaikan sendiri

   Silakan coba selesaikan sendiri terlebih dahulu berdasarkan informasi yang ada. Jika tidak dapat diselesaikan sendiri, untuk membantu staf EasyAR menentukan masalah dengan cepat, harap berikan informasi teknis yang rinci dan dapat direproduksi. Jangan hanya mendeskripsikan gejala seperti "layar hitam". Disarankan untuk memberikan umpan balik yang mencakup:

• Log lengkap: Log Unity atau Sense.
• Tangkapan layar (screenshot) atau rekaman layar (screen recording): Layar penuh saat terjadi layar hitam. Jika ada informasi diagnostik, pastikan terlihat dan ambil tangkapan layarnya.
• Informasi perangkat yang rinci: Model perangkat (misalnya iPhone 15, HUAWEI P40), versi sistem operasi (misalnya iOS 17.1, Android 14), versi EasyAR Sense, versi EasyAR Sense Unity Plugin, versi Unity, dll.

Tidak berjalan di tempat, terus NotFound

Pengembang menggunakan simulator atau rekaman layar untuk pengujian di kantor, tetapi tidak dapat menemukan lokasi. Kemungkinan penyebabnya adalah mode MegaLocationInputMode disetel ke Onsite, tetapi tidak dijalankan di lokasi. Perlu memilih mode yang benar selama pengembangan berdasarkan mode input lokasi Mega:

Constant	Value	Description
Onsite	0	Mode input untuk penggunaan di lokasi, data lokasi biasanya diperoleh dari perangkat dan dimasukkan ke Mega, biasanya ditangani secara internal oleh FrameFilter
Simulator	1	Mode input untuk penggunaan jarak jauh, data lokasi perlu disimulasikan sebagai data di lokasi dan dimasukkan ke Mega melalui antarmuka yang sesuai (opsional)
FramePlayer	2	Mode input saat menggunakan FramePlayer. Mode ini bersifat hanya-baca

Faktor lingkungan menyebabkan

Masalah ini muncul ketika layanan berfungsi normal, tetapi lokasi terus mengembalikan NotFound.

Terus-menerus notfound saat menghadap dinding putih atau lantai polos

Ketika gambar kamera menampilkan area besar dinding putih, kaca, atau lantai polos, status akan terus mengembalikan NotFound.

Sebab: Pelokalan visual bergantung pada fitur tekstur. Area dengan tekstur lemah tidak dapat mengekstrak titik fitur.

Solusi: Ini adalah fenomena normal. Pindahkan kamera ke area dengan tekstur yang kaya untuk memulai.

Di lokasi dan tekstur-kaya, tetapi berlangsung NotFound

Orang berada di lokasi, menghadap area bertekstur, tetapi tidak berhasil melakukan lokalisasi dalam waktu lama.

Kemungkinan penyebab:

• Perubahan pemandangan: Perbedaan lingkungan saat ini (seperti renovasi, penggantian poster, perubahan pencahayaan drastis) terlalu besar dibandingkan saat pemetaan.
• Cakupan pengambilan tidak mencukupi: Posisi berdiri pengguna berada di luar cakupan area yang dipetakan saat pengambilan data awal.

Solusi:

• Pindah ke area rute yang pernah diambil saat pemetaan awal dan coba lagi.
• Jika pemandangan telah mengalami perubahan permanen yang signifikan, perlu melakukan pengambilan data ulang dan memperbarui Block.

Disebabkan oleh layanan itu sendiri

Baru menambahkan block, terus wakingup

Saat baru menyelesaikan konfigurasi pustaka lokasi atau baru memulai pustaka lokasi, status layanan menunjukkan WakingUp atau NotFound untuk waktu yang lama. Ini karena layanan Mega memiliki mekanisme cold start, dan pemuatan pertama perlu dibangunkan dari cold storage. Pastikan koneksi jaringan lancar, tunggu sekitar 10~30 detik dan coba lagi.

Layanan mengembalikan pengecualian

Status Https	Kode status	Alasan
200	21	QPS melebihi batas
200	1040 x	Parameter, pustaka, atau data peta tidak benar, lihat deskripsi pesan spesifik
200	4000 x	Kesalahan tingkat algoritma, lihat deskripsi spesifik
401	-	Autentikasi gagal, lihat deskripsi pesan
404	-	Jalur input dalam URL tidak benar
50x	-	Kesalahan program server

Metode penyelesaian saat terjadi pengecualian layanan:

• Muncul batasan QPS: Hubungi staf bisnis EasyAR untuk ekspansi QPS
• Muncul kegagalan autentikasi: Selesaikan berdasarkan deskripsi pesan spesifik, masalah umum termasuk deviasi waktu perangkat yang terlalu besar dari waktu standar, API Key tidak memiliki izin CLS, dll.
• Kasus lain: Silakan berikan umpan balik kepada staf EasyAR untuk diselesaikan

Masalah umpan balik

Jika masalah masih belum teratasi setelah memeriksa langkah-langkah di atas, silakan kumpulkan informasi sesuai langkah-langkah berikut dan berikan umpan balik kepada tim dukungan teknis EasyAR.

Mengekspor informasi Layanan Posisi Mega

Masuk ke akun Anda di Mega Studio Unity, pilih repositori posisi yang mengalami anomali, lalu temukan tombol Ekspor Layanan Posisi Mega seperti yang ditunjukkan pada gambar di bawah. Format file yang Anda ekspor harus berupa MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json. Layanan Posisi Mega hanya berisi informasi Mega Block dan repositori posisi, tidak mengandung informasi sensitif lainnya.

Rekam file EIF

Jika mengalami masalah saat pengujian di ponsel, silakan gunakan Toolbox untuk merekam file EIF ponsel

Jika mengalami masalah saat pengujian di kacamata, silakan gunakan Toolbox untuk merekam file EIF kacamata

Jika Anda mengalami masalah di aplikasi Anda sendiri, Anda dapat menggunakan aplikasi Anda untuk merekam file EIF

Saat menggunakan aplikasi mini WeChat, Anda dapat menggunakan aplikasi mini untuk merekam file EIF

Perekaman gejala masalah menggunakan perangkat seperti ponsel, kacamata, dll.

Di bidang AR, deskripsi teks seringkali sulit menyampaikan informasi yang akurat, pemahaman setiap orang bisa sangat berbeda. Sementara itu, rekaman layar (screen recording) saat runtime adalah informasi yang sangat berguna, memungkinkan Anda dan staf EasyAR membangun pemahaman yang sama. Anda dapat menggunakan fungsi bawaan perangkat seperti ponsel, kacamata, atau perangkat lunak pihak ketiga untuk melakukan perekaman. Perlu diperhatikan bahwa proses screen-recording umumnya memengaruhi kinerja runtime, baik efek pelacakan (tracking) maupun kinerja secara keseluruhan dapat terpengaruh.

Catatan

Sebelum merekam layar, disarankan untuk merujuk pada Sample yang sesuai saat runtime, dan menampilkan beberapa informasi Debug yang diperlukan di layar. Saat menyediakan rekaman layar, Anda juga harus menyediakan data EIF yang sesuai selama periode perekaman.

Umpan balik masalah pengembangan Unity

Jika Anda mengalami masalah yang tidak biasa selama pengembangan Unity, Anda harus memeriksa satu per satu apakah Anda telah menyelesaikan 4 pemeriksaan berikut.

1. Sudah mencoba versi terbaru EasyAR Sense Unity Plugin. Versi baru biasanya mencakup perbaikan bug dan fitur baru. Disarankan untuk memperbarui ke versi terbaru terlebih dahulu.
2. Sudah membaca dokumen pengembangan EasyAR dan panduan Mega. Dokumen biasanya berisi penjelasan untuk berbagai situasi.
3. Sudah membaca log sistem dan Unity. Disarankan untuk menyertakan log lengkap saat mengajukan pertanyaan.
4. Sudah mencoba mereproduksi masalah dalam proyek Unity kosong atau di dalam Sample.

Jika Anda telah menyelesaikan keempat pemeriksaan di atas dan masih tidak dapat menyelesaikan masalah Anda, Anda dapat memberikan informasi lengkap di EasyAR Sense Unity Plugin dengan mengikuti alur di bawah ini, agar teknisi EasyAR dapat menganalisis dan menyelesaikan masalah Anda.

1. Di Unity -> EasyAR -> Sense, pilih Pertanyaan

   

2. Di Pertanyaan, Anda perlu memberikan informasi berikut:

   • Pilih lingkungan eksekusi tempat masalah terjadi. Hanya satu lingkungan yang dapat dipilih.
   • Salin informasi perangkat. Di EasyAR Session, setel DiagnosticsController.DumpSession menjadi Log, salin output satu frame dan tempelkan hasilnya di bawah.
     
   • Pilih semua fitur EasyAR yang digunakan saat masalah terjadi. Pilihan ganda didukung.
   • Pastikan Anda telah menyelesaikan keempat pemeriksaan di atas. Disarankan untuk menjelaskan cara mereproduksi masalah dalam Sample saat bertanya.
   • Klik ikon salin di kanan atas.
     
     Saat pertama membuka jendela Pertanyaan, informasi di bawah tidak ditampilkan sepenuhnya. Anda perlu memilih lingkungan dan fitur yang digunakan terlebih dahulu agar informasi ditampilkan.
     

3. Klik Pergi ke Tanya Jawab EasyAR di bawah untuk memberikan informasi yang disalin kepada pihak resmi EasyAR, atau berikan langsung kepada staf EasyAR.