Tutorial Build dan Kustomisasi Organic Maps untuk Navigasi Offline

Aplikasi navigasi berbasis Google Maps memang nyaman, tapi tidak semua developer atau startup ingin bergantung pada layanan pihak ketiga yang mengumpulkan data lokasi pengguna. Organic Maps hadir sebagai solusi open source yang menawarkan navigasi offline penuh tanpa pelacakan. Lebih menarik lagi, kode sumbernya terbuka untuk dikustomisasi.

Tutorial ini akan membahas cara build Organic Maps dari source untuk platform Android dan iOS. Kita juga akan menyentuh bagaimana melakukan kustomisasi dasar agar aplikasi bisa disesuaikan dengan kebutuhan spesifik.

Kenapa Organic Maps?

Organic Maps dibangun di atas data OpenStreetMap dan merupakan fork dari proyek MapsWithMe. Beberapa keunggulan yang membuatnya menarik bagi developer:

• 100% offline: semua fitur utama berfungsi tanpa koneksi internet

• Tidak ada tracker, iklan, atau phoning home

• Dukungan format bookmark KML, KMZ, GPX, dan GeoJSON

• Lisensi Apache 2.0 yang memungkinkan modifikasi komersial

Sejak Desember 2025, aplikasi ini sudah mencapai lebih dari 6 juta install di seluruh platform. Detail lebih lanjut bisa dibaca di repository resmi.

Prasyarat Build

Organic Maps menggunakan C++ sebagai core engine dengan binding ke platform native. Berikut dependency utama yang harus disiapkan:

1. CMake 3.22 atau lebih baru

2. Python 3 dengan pip

3. Android Studio dengan NDK untuk build Android

4. Xcode 14 atau lebih baru untuk build iOS

5. Qt 6 untuk tools desktop opsional

Pastikan kamu memiliki ruang disk minimal 20 GB karena repository cukup besar akibat data peta dan aset grafis.

Langkah 1: Clone Repository dan Submodule

Organic Maps memiliki beberapa submodule Git yang wajib diinisialisasi:

git clone --recursive https://github.com/organicmaps/organicmaps.git
cd organicmaps

Jika sudah clone tanpa recursive, jalankan perintah berikut untuk mengambil submodule yang tertinggal:

git submodule update --init --recursive

Proses ini bisa memakan waktu cukup lama karena beberapa submodule berisi data peta dan library eksternal.

Langkah 2: Setup Environment Build

Setelah repository siap, install Python dependencies untuk tools build:

pip install -r tools/requirements.txt

Untuk Android, set environment variable ANDROID_HOME dan pastikan NDK sudah terinstall melalui SDK Manager. Organic Maps umumnya menggunakan NDK r25c atau versi yang didokumentasikan di file konfigurasi CI.

Untuk iOS, pastikan Xcode Command Line Tools sudah terinstall:

xcode-select --install

Langkah 3: Build untuk Android

Proses build Android dikelola oleh Gradle dengan CMake sebagai native builder. Jalankan:

./gradlew assembleDebug

Perintah ini akan mengompilasi core engine C++ dan menghasilkan APK debug. Jika pertama kali build, proses bisa memakan waktu 30-60 menit tergantung spesifikasi mesin.

Setelah build selesai, APK akan tersedia di:

android/build/outputs/apk/debug/

Install ke device untuk testing:

adb install android/build/outputs/apk/debug/organicmaps-debug.apk

Langkah 4: Build untuk iOS

Build iOS sedikit berbeda karena menggunakan Xcode project generator. Jalankan:

./configure.sh
open iphone/Maps.xcodeproj

Atau jika menggunakan Xcode 15+ dengan workspace:

open iphone/OrganicMaps.xcworkspace

Pilih target device atau simulator, lalu tekan Build. Pastikan signing team sudah dikonfigurasi jika ingin deploy ke device fisik.

Langkah 5: Kustomisasi Style dan Data

Salah satu bagian paling menarik dari Organic Maps adalah sistem style yang mendefinisikan cara fitur peta dirender. File style berada di direktori data/styles dengan format khusus yang mirip CSS.

Untuk mengubah tampilan default, edit file di data/styles/clear/style-clear dan rebuild aplikasi. Perubahan bisa mencakup warna jalan, ukuran ikon, atau visibility layer tertentu.

Data peta juga bisa dikustomisasi. Meskipun proses generate peta dari raw OpenStreetMap data memerlukan toolchain tambahan, kamu bisa bereksperimen dengan region kecil menggunakan dokumentasi di docs/MAPS.md.

Tips Optimasi Build dan Troubleshooting

Build Organic Maps bisa memakan waktu lama jika tidak dioptimasi. Beberapa tips untuk mempercepat proses:

• Gunakan ccache untuk menyimpan hasil kompilasi object file dan mengurangi waktu build berikutnya

• Build hanya untuk arsitektur target (arm64-v8a untuk Android modern) daripada semua ABI

• Pastikan swap memory cukup besar jika build di mesin dengan RAM terbatas

Jika mengalami error saat build, periksa versi CMake dan NDK. Organic Maps sangat sensitif terhadap versi toolchain dan seringkali gagal build jika menggunakan NDK yang terlalu baru atau terlalu lama.

Langkah 6: Menambahkan Bahasa dan Lokalisasi

Organic Maps mendukung lebih dari 40 bahasa secara native. Jika kamu ingin menambahkan bahasa lokal atau mengubah terminologi tertentu, file terjemahan berada di direktori data/strings. Formatnya menggunakan file JSON yang terstruktur berdasarkan kategori fitur.

Setelah mengubah file terjemahan, jalankan script generate untuk memperbarui resource string di native code:

python3 tools/python/generate_localizations.py

Pastikan untuk menguji tampilan teks di device karena beberapa bahasa memiliki karakter yang lebih lebar dan bisa menyebabkan overflow pada UI yang sudah ada.

Distribusi dan Update Aplikasi Custom

Setelah berhasil melakukan kustomisasi, kamu perlu mempertimbangkan cara distribusi. Untuk penggunaan internal, cukup distribusikan APK atau IPA melalui platform enterprise seperti Firebase App Distribution atau internal TestFlight.

Perlu diingat bahwa nama dan logo Organic Maps dilindungi. Jika kamu berencana mendistribusikan versi modifikasi secara publik, ubah branding agar tidak menimbulkan kebingungan dengan aplikasi resmi. Dokumentasi lisensi Apache 2.0 menjelaskan detail tentang atribusi yang diperlukan.

Kesimpulan

Organic Maps membuktikan bahwa navigasi berkualitas tidak harus datang dengan kompromi privasi. Bagi developer mobile, codebase ini adalah studi kasus yang bagus untuk memahami bagaimana C++ core engine diintegrasikan dengan UI native Android dan iOS.

Jika kamu tertarik berkontribusi, mulai dari issues berlabel good first issue di repository GitHub Organic Maps. Komunitasnya aktif dan selalu terbuka terhadap pull request baru.