Mulai cepat: Membuat aplikasi Android dengan Azure Maps
Artikel ini menunjukkan cara menambahkan Azure Maps ke aplikasi Android. Berikut panduan langkah-langkah dasar:
- Menyiapkan lingkungan pengembangan Anda.
- Buat akun Azure Maps Anda.
- Dapatkan kunci primer Azure Maps Anda untuk digunakan dalam aplikasi.
- Referensikan pustaka Azure Maps dari proyek.
- Tambahkan kontrol Azure Maps ke aplikasi.
Catatan
Penghentian Azure Peta Android SDK
Azure Peta Native SDK untuk Android sekarang tidak digunakan lagi dan akan dihentikan pada 31/3/25. Untuk menghindari gangguan layanan, migrasikan ke Azure Peta Web SDK dengan 3/31/25. Untuk informasi selengkapnya, lihat Panduan migrasi Azure Peta Android SDK.
Prasyarat
Berlangganan Microsoft Azure. Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.
Android Studio. Jika Anda tidak memiliki Android Studio, Anda bisa mendapatkannya secara gratis dari Google.
Catatan
Banyak instruksi dalam mulai cepat ini dibuat menggunakan Android Studio Arctic Fox (2020.3.1). Jika Anda menggunakan versi Android Studio yang berbeda, langkah-langkah khusus untuk Android Studio mungkin berbeda.
Membuat akun Azure Maps
Buat akun Azure Maps baru menggunakan langkah-langkah berikut:
Di sudut kiri atas portal Microsoft Azure, pilih Buat sumber daya.
Di kotak Cari Marketplace, ketik Azure Maps, lalu pilih Azure Maps dari hasil pencarian.
Pilih tombol Buat.
Pada halaman Buat Akun Maps, masukkan nilai berikut ini:
- Langganan yang ingin Anda gunakan untuk akun ini.
- Nama Grup sumber daya untuk akun ini. Pilih Buat baru atau Gunakan grup sumber daya yang sudah ada.
- Nama akun baru Anda.
- Tingkat harga untuk akun ini. Pilih Gen2.
- Baca Ketentuan, dan centang kotak centang untuk mengonfirmasi bahwa Anda telah membaca dan menyetujui Pernyataan Lisensi dan Privasi.
- Pilih tombol Tinjau + buat.
- Setelah Anda memastikan bahwa semuanya benar di halaman Tinjau + buat , pilih tombol Buat .
Mendapatkan kunci langganan untuk akun Anda
Setelah akun Azure Peta Anda berhasil dibuat, ambil kunci langganan yang memungkinkan Anda mengkueri API Peta.
- Buka akun Azure Maps Anda di portal.
- Di panel kiri, pilih Autentikasi.
- Salin Kunci Primer dan simpan secara lokal untuk digunakan nanti dalam tutorial ini.
Catatan
Untuk tujuan keamanan, disarankan agar Anda memutar antara kunci primer dan sekunder Anda. Untuk memutar kunci, perbarui aplikasi Anda untuk menggunakan kunci sekunder, sebarkan, lalu tekan tombol cycle/refresh di samping kunci primer untuk menghasilkan kunci primer baru. Kunci primer lama akan dinonaktifkan. Untuk informasi selengkapnya tentang rotasi kunci, lihat Menyiapkan Azure Key Vault dengan rotasi dan audit kunci.
Membuat project di Android Studio
Selesaikan langkah-langkah berikut untuk membuat proyek baru dengan aktivitas kosong di Android Studio:
Mulai Android Studio dan pilih Baru dari menu File, lalu Proyek Baru...
Di layar Proyek Baru, pilih Telepon dan Tablet dari daftar Template di sisi kiri layar.
Pilih Aktivitas Kosong dari daftar template, lalu Berikutnya.
Di layar Aktivitas Kosong, masukkan nilai untuk bidang berikut ini:
- Nama. Masukkan AzureMapsApp.
- Nama paket. Gunakan com.example.azuremapsapp default.
- Simpan lokasi. Gunakan default atau pilih lokasi baru untuk menyimpan file proyek Anda. Hindari penggunaan spasi di jalur atau filename karena potensi masalah dengan alat NDK.
- Bahasa. Pilih Kotlin atau Java.
- SDK Minimum. Pilih
API 21: Android 5.0.0 (Lollipop)
sebagai SDK minimum. Ini adalah versi paling awal yang didukung oleh Azure Peta Android SDK.
Pilih Selesai untuk membuat proyek baru Anda.
Lihat dokumentasi Android Studio untuk bantuan selengkapnya dalam menginstal Android Studio dan membuat proyek baru.
Menyiapkan perangkat virtual
Android Studio memungkinkan Anda menyiapkan perangkat Android virtual di komputer. Dengan begitu, Anda dapat menguji aplikasi selama pengembangan.
Untuk menyiapkan Perangkat Virtual Android (AVD):
- Pilih Manajer AVD di menu Alat.
- Android Virtual Device Manager muncul. Pilih Buat Perangkat Virtual.
- Di kategori Telepon, pilih Nexus 5X, lalu pilih Berikutnya.
Untuk informasi selengkapnya tentang menyiapkan AVD, lihat Membuat dan mengelola perangkat virtual di dokumentasi Android Studio.
Menginstal Android SDK Azure Maps
Langkah selanjutnya dalam membangun aplikasi Anda adalah menginstal Android SDK Azure Maps. Selesaikan langkah-langkah ini untuk menginstal SDK:
Buka file pengaturan proyek settings.gradle dan tambahkan kode berikut ke bagian repositori:
maven {url "https://atlas.microsoft.com/sdk/android"}
Dalam file pengaturan proyek yang sama settings.gradle, ubah repositoriesMode menjadi
PREFER_SETTINGS
:repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
File pengaturan proyek Anda sekarang akan muncul sebagai berikut:
Buka file gradle.properties proyek, verifikasi bahwa
android.useAndroidX
danandroid.enableJetifier
keduanya diatur ketrue
.Jika file gradle.properties tidak menyertakan
android.useAndroidX
danandroid.enableJetifier
, tambahkan dua baris berikutnya ke akhir file:android.useAndroidX=true android.enableJetifier=true
Buka file build.gradle aplikasi dan lakukan hal berikut:
Pastikan minSdk proyek Anda adalah 21 atau lebih tinggi.
Pastikan
compileOptions
Anda di bagianAndroid
adalah sebagai berikut:compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 }
Perbarui blok dependensi Anda dan tambahkan dependensi penerapan baru untuk Azure Maps Android SDK terbaru:
implementation 'com.azure.android:azure-maps-control:1.+'
Pilih Sinkronkan Proyek dengan File Gradle dari menu File.
Tambahkan fragmen peta ke aktivitas utama:
<com.azure.android.maps.control.MapControl android:id="@+id/mapcontrol" android:layout_width="match_parent" android:layout_height="match_parent" />
Untuk memperbarui aktivitas utama, pilih aplikasi > res > tata letak >activity_main.xml di Navigator proyek:
Dalam file MainActivity.java:
- Tambahkan impor untuk Azure Maps SDK.
- Mengatur informasi autentikasi Azure Maps Anda.
- Dapatkan instans kontrol peta dalam metode onCreate.
Tip
Dengan mengatur informasi autentikasi secara global di kelas
AzureMaps
menggunakan metodesetSubscriptionKey
atausetAadProperties
, Anda tidak perlu menambahkan informasi autentikasi di setiap tampilan.Kontrol peta berisi metode siklus hidupnya sendiri untuk mengelola siklus hidup OpenGL Android. Metode siklus hidup ini harus dipanggil langsung dari Aktivitas yang berisi di dalamnya. Untuk memanggil metode siklus hidup kontrol peta dengan benar, ambil alih metode siklus hidup berikut dalam Aktivitas yang berisi kontrol peta, lalu panggil metode kontrol peta masing-masing.
onCreate(Bundle)
onDestroy()
onLowMemory()
onPause()
onResume()
onSaveInstanceState(Bundle)
onStart()
onStop()
Edit file MainActivity.java sebagai berikut:
package com.example.azuremapsapp; import androidx.appcompat.app.AppCompatActivity; import android.os.Bundle; import com.azure.android.maps.control.AzureMaps; import com.azure.android.maps.control.MapControl; import com.azure.android.maps.control.layer.SymbolLayer; import com.azure.android.maps.control.options.MapStyle; import com.azure.android.maps.control.source.DataSource; public class MainActivity extends AppCompatActivity { static { AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>"); //Alternatively use Azure Active Directory authenticate. //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>"); } MapControl mapControl; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); mapControl = findViewById(R.id.mapcontrol); mapControl.onCreate(savedInstanceState); //Wait until the map resources are ready. mapControl.onReady(map -> { //Add your post map load code here. }); } @Override public void onResume() { super.onResume(); mapControl.onResume(); } @Override protected void onStart(){ super.onStart(); mapControl.onStart(); } @Override public void onPause() { super.onPause(); mapControl.onPause(); } @Override public void onStop() { super.onStop(); mapControl.onStop(); } @Override public void onLowMemory() { super.onLowMemory(); mapControl.onLowMemory(); } @Override protected void onDestroy() { super.onDestroy(); mapControl.onDestroy(); } @Override protected void onSaveInstanceState(Bundle outState) { super.onSaveInstanceState(outState); mapControl.onSaveInstanceState(outState); }}
Dalam file MainActivity.kt:
- tambahkan impor untuk SDK Azure Maps
- mengatur informasi autentikasi Azure Maps Anda
- dapatkan instans kontrol peta dalam metode onCreate
Tip
Dengan mengatur informasi autentikasi secara global di kelas
AzureMaps
menggunakan metodesetSubscriptionKey
atausetAadProperties
, Anda tidak perlu menambahkan informasi autentikasi di setiap tampilan.Kontrol peta berisi metode siklus hidupnya sendiri untuk mengelola siklus hidup OpenGL Android. Metode siklus hidup ini harus dipanggil langsung dari Aktivitas yang berisi di dalamnya. Untuk memanggil metode siklus hidup kontrol peta dengan benar, ambil alih metode siklus hidup berikut dalam Aktivitas yang berisi kontrol peta. Dan, Anda harus memanggil metode kontrol peta masing-masing.
onCreate(Bundle)
onDestroy()
onLowMemory()
onPause()
onResume()
onSaveInstanceState(Bundle)
onStart()
onStop()
Edit file MainActivity.kt sebagai berikut:
package com.example.azuremapsapp; import androidx.appcompat.app.AppCompatActivity import android.os.Bundle import com.azure.android.maps.control.AzureMap import com.azure.android.maps.control.AzureMaps import com.azure.android.maps.control.MapControl import com.azure.android.maps.control.events.OnReady class MainActivity : AppCompatActivity() { companion object { init { AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>"); //Alternatively use Azure Active Directory authenticate. //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>"); } } var mapControl: MapControl? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) mapControl = findViewById(R.id.mapcontrol) mapControl?.onCreate(savedInstanceState) //Wait until the map resources are ready. mapControl?.onReady(OnReady { map: AzureMap -> }) } public override fun onStart() { super.onStart() mapControl?.onStart() } public override fun onResume() { super.onResume() mapControl?.onResume() } public override fun onPause() { mapControl?.onPause() super.onPause() } public override fun onStop() { mapControl?.onStop() super.onStop() } override fun onLowMemory() { mapControl?.onLowMemory() super.onLowMemory() } override fun onDestroy() { mapControl?.onDestroy() super.onDestroy() } override fun onSaveInstanceState(outState: Bundle) { super.onSaveInstanceState(outState) mapControl?.onSaveInstanceState(outState) } }
Pilih tombol jalankan dari toolbar, seperti yang ditunjukkan pada gambar berikut (atau tekan
Control
+R
di Mac), untuk membangun aplikasi Anda.
Android Studio membutuhkan waktu beberapa detik untuk membuat aplikasi. Setelah proses pembangunan aplikasi selesai, Anda dapat menguji aplikasi di perangkat Android yang ditiru. Anda akan melihat peta seperti ini:
Tip
Secara default, Android memuat ulang aktivitas saat orientasi berubah atau keyboard disembunyikan. Ini menghasilkan status peta yang direset (muat ulang peta yang mengatur ulang tampilan dan memuat ulang data ke status awal). Untuk mencegah hal ini terjadi, tambahkan yang berikut ini ke mainfest: android:configChanges="orientation|keyboardHidden"
. Ini akan menghentikan aktivitas dari pemuatan ulang dan sebaliknya memanggil onConfigurationChanged()
ketika orientasi telah berubah atau keyboard disembunyikan.
Membersihkan sumber daya
Peringatan
Tutorial yang tercantum di bagian Langkah Berikutnya memerinci cara menggunakan dan mengonfigurasi Azure Maps dengan akun Anda. Jangan hapus sumber daya yang dibuat dalam mulai cepat ini jika Anda ingin melanjutkan ke tutorial.
Jika Anda tidak ingin melanjutkan ke tutorial, lakukan langkah-langkah ini untuk menghapus sumber daya:
- Tutup Android Studio dan hapus aplikasi yang Anda buat.
- Jika Anda menguji aplikasi di perangkat eksternal, hapus instalan aplikasi dari perangkat tersebut.
Jika Anda tidak berencana untuk terus mengembangkan aplikasi dengan Android SDK Azure Maps:
- Buka halaman portal Microsoft Azure. Pilih Semua sumber daya dari halaman portal utama.
- Pilih akun Azure Maps Anda. Di bagian atas halaman, pilih Hapus.
- Jika tidak berencana untuk terus mengembangkan aplikasi Android, Anda memiliki opsi untuk menghapus instalan Android Studio.
Untuk contoh kode lainnya, lihat panduan berikut:
- Kelola autentikasi di Azure Maps
- Ubah gaya peta di peta Android
- Menambah lapisan simbol
- Menambah lapisan baris
- Menambah lapisan poligon
Langkah berikutnya
Dalam mulai cepat ini, Anda membuat akun Azure Maps dan membuat aplikasi demo. Lihat tutorial berikut untuk mempelajari selengkapnya tentang Azure Maps: