Mulai cepat: Membuat aplikasi Android dengan Azure Maps

  • Artikel

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

  1. Berlangganan Microsoft Azure. Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

  2. 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:

  1. Di sudut kiri atas portal Microsoft Azure, pilih Buat sumber daya.

  2. Di kotak Cari Marketplace, ketik Azure Maps, lalu pilih Azure Maps dari hasil pencarian.

  3. Pilih tombol Buat.

  4. 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 .

    Cuplikan layar yang menampilkan panel Membuat akun Maps di portal Azure.

Mendapatkan kunci langganan untuk akun Anda

Setelah akun Azure Peta Anda berhasil dibuat, ambil kunci langganan yang memungkinkan Anda mengkueri API Peta.

  1. Buka akun Azure Maps Anda di portal.
  2. Di panel kiri, pilih Autentikasi.
  3. 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.

Cuplikan layar memperlihatkan kunci langganan Azure Peta Anda di portal Azure.

Membuat project di Android Studio

Selesaikan langkah-langkah berikut untuk membuat proyek baru dengan aktivitas kosong di Android Studio:

  1. Mulai Android Studio dan pilih Baru dari menu File, lalu Proyek Baru...

  2. Di layar Proyek Baru, pilih Telepon dan Tablet dari daftar Template di sisi kiri layar.

    Cuplikan layar yang menampilkan layar Proyek Baru di Android Studio.

  3. Pilih Aktivitas Kosong dari daftar template, lalu Berikutnya.

    Cuplikan layar yang menampilkan layar Membuat Aktivitas Kosong di Android Studio.

  4. 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.

  5. 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):

  1. Pilih Manajer AVD di menu Alat.
  2. Android Virtual Device Manager muncul. Pilih Buat Perangkat Virtual.
  3. 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.

Cuplikan layar yang menampilkan layar Memilih Perangkat Keras di Android Virtual Device Manager saat membuat Perangkat Virtual baru.

Menginstal Android SDK Azure Maps

Langkah selanjutnya dalam membangun aplikasi Anda adalah menginstal Android SDK Azure Maps. Selesaikan langkah-langkah ini untuk menginstal SDK:

  1. Buka file pengaturan proyek settings.gradle dan tambahkan kode berikut ke bagian repositori:

    maven {url "https://atlas.microsoft.com/sdk/android"}

  2. 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:

    Cuplikan layar file pengaturan proyek di Android Studio.

  3. Buka file gradle.properties proyek, verifikasi bahwa android.useAndroidX dan android.enableJetifier keduanya diatur ke true.

    Jika file gradle.properties tidak menyertakan android.useAndroidX dan android.enableJetifier, tambahkan dua baris berikutnya ke akhir file:

    android.useAndroidX=true
android.enableJetifier=true

  4. Buka file build.gradle aplikasi dan lakukan hal berikut:

    1. Pastikan minSdk proyek Anda adalah 21 atau lebih tinggi.

    2. Pastikan compileOptions Anda di bagian Android adalah sebagai berikut:

      compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

    3. Perbarui blok dependensi Anda dan tambahkan dependensi penerapan baru untuk Azure Maps Android SDK terbaru:

      implementation 'com.azure.android:azure-maps-control:1.+'

    4. Pilih Sinkronkan Proyek dengan File Gradle dari menu File.

    Cuplikan layar yang menampilkan file build.gradle aplikasi di Android Studio.

  5. 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:

    Cuplikan layar yang menampilkan file activity_main.xml di Android Studio.

  1. 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 metode setSubscriptionKey atau setAadProperties, 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);
}}

  1. 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 metode setSubscriptionKey atau setAadProperties, 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)
    }
}

  1. Pilih tombol jalankan dari toolbar, seperti yang ditunjukkan pada gambar berikut (atau tekan Control + R di Mac), untuk membangun aplikasi Anda.

    Cuplikan layar yang menampilkan tombol jalankan di Android Studio.

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:

Cuplikan layar yang menampilkan Azure Maps di aplikasi Android.

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:

  1. Tutup Android Studio dan hapus aplikasi yang Anda buat.
  2. 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:

  1. Buka halaman portal Microsoft Azure. Pilih Semua sumber daya dari halaman portal utama.
  2. Pilih akun Azure Maps Anda. Di bagian atas halaman, pilih Hapus.
  3. Jika tidak berencana untuk terus mengembangkan aplikasi Android, Anda memiliki opsi untuk menghapus instalan Android Studio.

Untuk contoh kode lainnya, lihat panduan berikut:

Langkah berikutnya

Dalam mulai cepat ini, Anda membuat akun Azure Maps dan membuat aplikasi demo. Lihat tutorial berikut untuk mempelajari selengkapnya tentang Azure Maps:

Tutorial: Memuat data GeoJSON ke Azure Peta Android SDK