Panduan Pemecahan Masalah Kegagalan Lokalisasi Mega

Mega berbasis algoritma lokalisasi visual canggih. Dengan pencarian Mega Block di cloud serta pencocokan dan penyelesaian fitur visual, Mega mewujudkan lokalisasi presisi tinggi. Karena itu dalam penggunaan aktual, kegagalan lokalisasi dapat terjadi akibat berbagai alasan seperti kesalahan konfigurasi, perubahan lingkungan, atau fluktuasi jaringan.

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

Alur Lokalisasi

Anda perlu mengumpulkan data pemetaan di area target dan membangun Mega Block, menambahkan Mega Block yang telah direkonstruksi ke localization library, dan memastikan localization library tersedia.

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

Menilai Status Lokalisasi

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

  

• Jika Anda adalah pengembang Unity dan lokalisasi gagal, Anda dapat melihat informasi spesifik yang dikembalikan lokalisasi, yaitu MegaTrackerLocalizationStatus, pada layar. Jika informasi ini tidak ada di layar, Anda perlu mengaktifkan informasi diagnosis.

  

Nilai yang mungkin untuk MegaTrackerLocalizationStatus

Constant	Value	Description
UnknownError	0	Error tidak diketahui
Found	1	Berhasil melokalisasi ke Block
NotFound	2	Tidak menemukan Block
RequestTimeout	3	Request timeout (lebih dari 1 menit)
RequestIntervalTooLow	4	Interval request terlalu pendek
QpsLimitExceeded	5	QPS melebihi batas
WakingUp	6	Layanan sedang dibangunkan
MissingSpotVersionId	7	SpotVersionId hilang, mungkin belum diatur
ApiTokenExpired	8	API Token kedaluwarsa

Solusi untuk exception di atas:

• Request timeout: periksa dan perbaiki kondisi jaringan. Jika perlu, tingkatkan waktu timeout request MegaRequestTimeParameters.Timeout. Namun kondisi jaringan yang buruk juga akan memengaruhi efek tracking, sehingga masalah jaringan perlu diselesaikan sebisa mungkin.
• Interval request terlalu pendek: kurangi frekuensi request.
• Koneksi atau transmisi gagal: periksa dan perbaiki kondisi jaringan.
• QPS melebihi batas: hubungi tim bisnis EasyAR untuk peningkatan kapasitas QPS.
• Layanan sedang dibangunkan: sistem sedang dalam proses waking up. Tunggu beberapa saat lalu coba lagi.
• SpotVersionId hilang: konfigurasi SpotVersionId.
• API Token kedaluwarsa: buat ulang API Token di backend manajemen EasyAR.

UnknownError umumnya memiliki dua kondisi:

• Koneksi atau transmisi gagal
• Layanan mengembalikan exception

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

Kategori Umum Error dan Pemeriksaannya

Menurut status dan fenomena yang dikembalikan lokalisasi, masalah umum dapat dibagi menjadi tiga kategori: masalah konfigurasi, faktor lingkungan, dan layanan itu sendiri.

Masalah Konfigurasi

Masalah jenis ini biasanya terjadi pada tahap integrasi pengembangan, dengan gejala layanan sama sekali tidak dapat dimulai.

Terkait License

Jika selama proses pengembangan atau pengujian, log atau layar menampilkan masalah seperti License atau Invalid Key, kemungkinan penyebabnya adalah AppID/BundleID tidak cocok, License kedaluwarsa, paket tidak sesuai, dan lainnya. Periksa pengaturan License Anda sesuai tabel berikut.

Error	Solusi
Invalid Key: No matched Bundle ID	Bundle ID tidak cocok dengan license key. Ubah salah satunya agar cocok
Invalid Key: No matched Package Name	Bundle ID tidak cocok dengan license key. Ubah salah satunya agar cocok
Invalid Key: License does not apply to current variant	Menggunakan SDK paket enterprise tetapi license key bukan enterprise, atau menggunakan SDK non-enterprise tetapi memakai license key paket enterprise
Invalid Key: License for an old version does not apply	Versi license terlalu lama, buat license baru
Invalid Key: Invalid format	Format license salah, misalnya tidak tersalin lengkap
Invalid Key: Server verification failed	License telah dihapus atau tidak memiliki izin penggunaan perangkat. Jika digunakan pada headset, hubungi bisnis untuk menambahkan izin
License does not apply to eyewear	License tidak dapat digunakan pada headset/kacamata, ganti dengan xr license
License is expired	License telah kedaluwarsa

Selain itu, Anda perlu memperhatikan bahwa License versi uji coba memiliki beberapa batasan. Penggunaan EasyAR Sense versi berbayar dan layanan EasyAR Mega berbayar dapat menyelesaikan masalah ini. Jika Anda sudah menggunakan EasyAR Sense versi berbayar, Anda dapat mengabaikan atau langsung menghapus teks terkait dari sample.

Abnormalitas Gambar Kamera

Dalam proses pengembangan atau pengujian aplikasi EasyAR Mega, jika muncul masalah abnormal seperti layar hitam, crash, atau kamera tidak menampilkan gambar, ikuti langkah berikut untuk memeriksa dan mengumpulkan informasi secara sistematis.

1. Coba selesaikan sendiri

• Jika Anda menggunakan Unity untuk pengembangan dan pengujian, pastikan Diagnostics Controller (Script) telah dicentang di AR Session (EasyAR) -> Inspector untuk mengaktifkan informasi diagnosis.

  

• Lihat konten yang ditampilkan pada layar atau log, dan periksa apakah UI memiliki petunjuk teks yang jelas.

• Pada sebagian besar kasus, pesan error bersifat menjelaskan sendiri. Jika informasi layar atau log sudah menjelaskan penyebab error, selesaikan berdasarkan penyebab spesifik. Contoh: cameraDevice.openWithPreferredType fail (perlu memeriksa apakah kamera tersedia).

• Jika muncul petunjuk "tidak didukung" (misalnya perangkat tidak mendukung ARCore atau fitur lain), itu termasuk batasan normal dan tidak perlu pemeriksaan lebih lanjut.

2. Tidak dapat menyelesaikan sendiri

   Cobalah menyelesaikan sendiri terlebih dahulu berdasarkan informasi yang ada. Jika masih tidak dapat diselesaikan, untuk membantu staf EasyAR melokalisasi masalah dengan cepat, pastikan Anda menyediakan informasi teknis yang detail dan dapat direproduksi. Jangan hanya mendeskripsikan fenomena seperti "layar hitam". Konten umpan balik yang disarankan meliputi:

• Log lengkap: Unity atau Sense
• Screenshot atau rekaman layar: layar lengkap saat layar hitam. Jika ada informasi diagnosis, pastikan terlihat dan ambil screenshot.
• Informasi perangkat detail: model perangkat (misalnya iPhone 15, HUAWEi P40), versi sistem (misalnya iOS 17.1, Android 14), versi EasyAR Sense, versi EasyAR Sense Unity Plugin, versi Unity, dan lainnya.

Tidak Berjalan di Lokasi, Terus NotFound

Pengembang menggunakan simulator atau rekaman layar di kantor untuk pengujian, tetapi selalu tidak dapat melokalisasi. Kemungkinan penyebabnya adalah mode MegaLocationInputMode diatur ke Onsite, padahal tidak berjalan di lokasi. Pada proses pengembangan, pilih mode yang benar sesuai 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 diproses secara internal oleh FrameFilter
Simulator	1	Mode input untuk penggunaan jarak jauh. Data lokasi perlu disimulasikan sebagai data lokasi dan dimasukkan ke Mega melalui interface terkait (opsional)
FramePlayer	2	Mode input saat menggunakan FramePlayer. Mode ini hanya baca

Disebabkan Faktor Lingkungan

Masalah jenis ini ditandai dengan layanan yang normal, tetapi lokalisasi terus mengembalikan NotFound.

Menghadap Dinding Putih atau Lantai dan Terus NotFound

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

Penyebab: Lokalisasi visual bergantung pada fitur tekstur. Area bertekstur lemah tidak dapat mengekstrak feature point.

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

Di Lokasi dan Tekstur Kaya, tetapi Terus NotFound

Pengguna berada di lokasi dan menghadap area bertekstur, tetapi lokalisasi tetap gagal dalam waktu lama.

Kemungkinan penyebab:

• Perubahan scene: lingkungan lokasi (seperti renovasi, pergantian poster, perubahan pencahayaan drastis) terlalu berbeda dari saat pemetaan.
• Akuisisi tidak mencakup area tersebut: posisi berdiri pengguna berada di luar cakupan pemetaan yang dikumpulkan sebelumnya.

Solusi:

• Pindah ke area rute akuisisi sebelumnya dan coba lagi.
• Jika scene telah mengalami perubahan permanen yang besar, perlu mengumpulkan ulang data dan memperbarui Block.

Disebabkan Layanan Itu Sendiri

Baru Menambahkan Block, Terus WakingUp

Saat localization library baru selesai dikonfigurasi atau baru dimulai, status layanan menampilkan WakingUp atau NotFound dalam waktu lama. Karena layanan Mega memiliki mekanisme cold start, pemuatan pertama perlu dibangunkan dari cold storage. Pastikan jaringan lancar, tunggu 10-30 detik, lalu coba lagi.

Layanan Mengembalikan Exception

Https status	Status code	Penyebab
200	21	QPS melebihi batas
200	1040 x	Parameter, library, atau data peta tidak benar; lihat deskripsi pesan spesifik
200	4000 x	Error tingkat algoritma; lihat deskripsi spesifik
401	-	Autentikasi gagal; lihat deskripsi pesan spesifik
404	-	Path dalam URL dimasukkan dengan tidak benar
50x	-	Error program server

Solusi ketika layanan exception:

• Jika muncul batas QPS: hubungi tim bisnis EasyAR untuk peningkatan kapasitas QPS.
• Jika muncul kegagalan autentikasi: selesaikan berdasarkan deskripsi pesan spesifik. Masalah umum meliputi perbedaan waktu perangkat dengan waktu standar terlalu besar, API Key tidak memiliki izin CLS, dan lainnya.
• Situasi lainnya: beri umpan balik kepada staf EasyAR untuk diselesaikan.

Umpan Balik Masalah

Jika masalah tetap tidak dapat diselesaikan setelah pemeriksaan di atas, kumpulkan informasi dan berikan umpan balik kepada tim dukungan teknis EasyAR sesuai langkah berikut.

Mengekspor Informasi Layanan Lokalisasi Mega

• Pengembangan Unity, versi plugin >= 4003
• Pengembangan Unity, versi plugin 4.7 - 4002
• Pengembangan Mini Program
• Skenario Penggunaan Mega Studio Lainnya

Pada alat editor node block yang Anda gunakan, klik tombol Diagnosis Info pada gambar berikut untuk mengekspor informasi diagnosis Mega Block. Informasi diagnosis Mega Block hanya berisi informasi Mega Block dan localization library, tidak berisi informasi sensitif lainnya.

Format file yang Anda ekspor seharusnya adalah Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json.

Merekam File EIF

Jika masalah terjadi saat pengujian dengan ponsel, gunakan Toolbox untuk merekam file EIF ponsel.

Jika masalah terjadi saat pengujian dengan kacamata, gunakan Toolbox untuk merekam file EIF kacamata.

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

Saat menggunakan WeChat Mini Program, Anda dapat menggunakan Mini Program untuk merekam file EIF.

Merekam Fenomena Masalah Menggunakan Ponsel, Kacamata, dan Perangkat Lain

Di bidang AR, deskripsi teks biasanya sulit menyampaikan informasi yang akurat, dan pemahaman setiap orang dapat sangat berbeda. Pada saat yang sama, rekaman layar saat runtime adalah informasi yang sangat berguna, karena dapat membantu Anda dan staf EasyAR membangun pemahaman yang sama. Anda dapat menggunakan fungsi bawaan ponsel, kacamata, dan perangkat lain, atau menggunakan perangkat lunak pihak ketiga untuk merekam. Perlu diperhatikan bahwa proses perekaman layar umumnya memengaruhi efek berjalan, dan efek tracking maupun performa dapat terpengaruh.

Catatan

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

Umpan Balik Masalah Pengembangan Unity

Jika Anda mengalami masalah abnormal saat menggunakan Unity untuk pengembangan, periksa satu per satu apakah 4 item berikut telah diselesaikan.

1. Sudah mencoba versi terbaru EasyAR Sense Unity Plugin. Versi baru biasanya berisi perbaikan bug dan fitur baru, disarankan mencoba upgrade ke versi terbaru terlebih dahulu
2. Sudah membaca dokumen pengembangan EasyAR dan panduan Mega. Dokumen biasanya berisi penjelasan untuk beberapa kondisi
3. Sudah membaca log sistem dan Unity. Disarankan menyediakan log lengkap saat mengajukan pertanyaan
4. Sudah mencoba mereproduksi masalah pada Sample dalam proyek Unity kosong

Jika 4 pemeriksaan di atas sudah selesai tetapi masalah masih belum dapat diselesaikan, Anda dapat memberikan informasi lengkap melalui EasyAR Sense Unity Plugin sesuai alur berikut agar teknisi EasyAR dapat menganalisis dan menyelesaikan masalah.

1. Di Unity -> EasyAR -> Sense, pilih Ask Question

   

2. Di Ask Question, Anda perlu menyediakan informasi berikut

   • Pilih runtime environment yang bermasalah; hanya satu environment yang dapat dipilih
   • Salin informasi perangkat. Di EasyAR Session, atur DiagnosticsController.DumpSession ke Log, salin output satu frame, lalu isi hasilnya di bagian bawah
   • Pilih semua fitur EasyAR yang digunakan saat masalah terjadi; mendukung pilihan ganda
   • Pastikan 4 pemeriksaan di atas sudah selesai. Disarankan menjelaskan cara mereproduksi masalah di Sample saat mengajukan pertanyaan
   • Klik fungsi salin di kanan atas Saat jendela Ask Question baru dibuka, informasi di bagian bawah tidak ditampilkan lengkap. Informasi tersebut baru akan muncul setelah Anda memilih environment dan fitur yang digunakan.

3. Klik Go to EasyAR Q&A di bawah untuk mengirim informasi yang disalin kepada EasyAR resmi, atau langsung kirimkan kepada staf EasyAR.