Panduan Memulai Maps SDK for Android

Buat aplikasi Android yang menampilkan peta dengan menggunakan template Google Maps Views untuk Android Studio. Jika Anda sudah memiliki project Android Studio yang ingin disiapkan, lihat Menyiapkan project Android Studio.

Panduan memulai ini ditujukan bagi developer yang sudah memahami pengembangan Android dasar dengan Kotlin atau Java.

Tentang lingkungan pengembangan

Panduan memulai ini dikembangkan menggunakan Android Studio Hedgehog dan plugin Android Gradle versi 8.2.

Catatan: Jika lingkungan pengembangan Anda menggunakan Android Studio atau Gradle dengan versi yang berbeda, Anda mungkin harus mengubah langkah-langkahnya berdasarkan lingkungan Anda. Untuk informasi selengkapnya mengenai versi Android Studio dan Gradle, lihat kompatibilitas plugin Android Gradle dan Android Studio.

Menyiapkan perangkat Android

Untuk menjalankan aplikasi yang menggunakan Maps SDK for Android, Anda harus men-deploy aplikasi tersebut ke perangkat Android atau emulator Android yang menggunakan Android 5.0 atau yang lebih tinggi dan menyertakan Google API.

• Untuk menggunakan perangkat Android, ikuti petunjuk pada halaman Menjalankan aplikasi di perangkat hardware.
• Untuk menggunakan Android Emulator, Anda dapat membuat perangkat virtual dan menginstal emulator dengan menggunakan AVD (Perangkat Virtual Android) Manager yang disertakan bersama Android Studio.
  Catatan: Jika memilih untuk menggunakan emulator Android, pastikan Anda memilih perangkat yang memiliki ikon Google Play, , yang ditampilkan di bawah kolom Play Store. Ikon ini menunjukkan bahwa profil tersebut sepenuhnya kompatibel dengan CTS dan dapat menggunakan image sistem yang menyertakan aplikasi Play Store:

  

Membuat project Google Maps di Android Studio

Prosedur untuk membuat project Google Maps di Android Studio telah diubah dalam Android Studio versi Flamingo ke atas.

1. Buka Android Studio, lalu klik New Project di jendela Welcome to Android Studio.

2. Di jendela New Project, dalam kategori Phone and Tablet, pilih No Activity, lalu klik Next.

3. Lengkapi formulir New Project:

   • Setel Language ke Java atau Kotlin. Kedua bahasa didukung sepenuhnya oleh Maps SDK for Android. Untuk mempelajari Kotlin lebih lanjut, lihat halaman Mengembangkan aplikasi Android dengan Kotlin.

   • Tetapkan Minimum SDK ke versi SDK yang kompatibel dengan perangkat pengujian Anda. Anda harus memilih versi yang lebih tinggi dari versi minimum yang diperlukan oleh Maps SDK for Android versi 19.0.x, yaitu Android API Level 21 ("Lollipop"; Android 5.0) atau yang lebih tinggi. Lihat Catatan Rilis untuk mengetahui informasi terbaru tentang persyaratan versi SDK.

     Catatan: Jika Anda tidak yakin dengan versi SDK yang harus dipilih, klik link Bantu saya memilih untuk menampilkan informasi distribusi untuk Android SDK yang didukung. Misalnya, jika Anda memilih Android API Level 21 ("Lollipop"; Android 5.0), aplikasi Anda seharusnya dapat dijalankan di lebih dari 99% perangkat Android.

   • Tetapkan Build configuration language ke Kotlin DSL atau Groovy DSL. Cuplikan untuk kedua bahasa konfigurasi build tersebut ditampilkan di prosedur berikut.

4. Klik Finish.

   Android Studio memulai Gradle dan membuat project. Proses ini mungkin berlangsung lama.

5. Tambahkan Google Maps Views Activity:

   1. Klik kanan pada folder app di project Anda.

   2. Pilih New > Google > Google Maps Views Activity.

      

   3. Di kotak dialog New Android Activity, centang kotak Launcher Activity.

   4. Pilih Finish.

      Untuk informasi selengkapnya, lihat Menambahkan kode dari template

6. Setelah proses build selesai, Android Studio akan membuka file AndroidManifest.xml dan MapsActivity. Aktivitas Anda mungkin memiliki nama berbeda, tetapi yang akan digunakan adalah nama yang dikonfigurasi selama penyiapan.

   Perhatian: File AndroidManifest.xml berisi petunjuk cara mendapatkan kunci API Google Maps dan menambahkannya ke file local.properties Anda. Jangan tambahkan kunci API Anda ke file local.properties. Tindakan tersebut akan mengurangi keamanan penyimpanan kunci API. Sebagai gantinya, ikuti petunjuk di Menyiapkan project Google Cloud untuk membuat project Cloud dan mengonfigurasi kunci API.

Menyiapkan project Google Cloud

Selesaikan langkah-langkah penyiapan konsol Cloud yang diperlukan dengan mengklik tab berikut:

Langkah 1

Konsol

1. Di konsol Google Cloud, pada halaman pemilih project, klik Create Project untuk mulai membuat project Cloud baru.

   Buka halaman pemilih project

2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Konfirmasi bahwa penagihan diaktifkan untuk project Anda.

   Google Cloud menawarkan uji coba tanpa biaya. Masa uji coba berakhir setelah 90 hari atau setelah akumulasi tagihan akun mencapai $300, mana saja yang lebih dulu. Batalkan kapan saja. Google Maps Platform memberikan kredit bulanan berulang sebesar $200. Untuk informasi selengkapnya, lihat Kredit akun penagihan dan Penagihan.

Cloud SDK

gcloud projects create "PROJECT"

Baca selengkapnya tentang Google Cloud SDK, Penginstalan Cloud SDK, dan perintah berikut:

• gcloud projects create

Catatan: Jika Anda tidak ingin menyimpan resource yang dibuat dalam latihan pembelajaran, buatlah project, alih-alih memilih project yang sudah ada. Setelah menyelesaikan latihan ini, Anda dapat menghapus project, sehingga semua resource yang terkait dengan project tersebut akan dihapus.

Langkah 2

Untuk menggunakan Google Maps Platform, Anda harus mengaktifkan API atau SDK yang akan digunakan dengan project.

Konsol

Mengaktifkan Maps SDK for Android

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

Baca selengkapnya tentang Google Cloud SDK, Penginstalan Cloud SDK, dan perintah berikut:

• gcloud services enable
• gcloud services disable

Langkah 3

Langkah ini hanya ada di proses pembuatan Kunci API. Jika Anda menggunakan Kunci API dalam produksi, kami sangat menyarankan agar Anda membatasi kunci API. Anda dapat menemukan informasi selengkapnya di halaman Menggunakan Kunci API spesifik per produk.

Kunci API adalah ID unik yang mengautentikasi permintaan terkait project untuk tujuan penggunaan dan penagihan. Anda harus memiliki setidaknya satu kunci API terkait project.

Untuk membuat kunci API:

Konsol

1. Buka halaman Google Maps Platform > Credentials.

   Buka halaman Credentials

2. Pada halaman Credentials, klik Create credentials > API key.
   Dialog API key created akan menampilkan kunci API yang baru dibuat.
3. Klik Close.
   Kunci API baru dicantumkan pada halaman Credentials di bawah API keys.
   (Jangan lupa untuk membatasi kunci API sebelum menggunakannya dalam produksi.)

Cloud SDK

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Baca selengkapnya tentang Google Cloud SDK, Penginstalan Cloud SDK, dan perintah berikut:

• gcloud services api-keys create

Menambahkan kunci API ke aplikasi

Bagian ini menjelaskan cara menyimpan kunci API sehingga dapat dirujuk dengan aman oleh aplikasi Anda. Anda tidak boleh memasukkan kunci API ke dalam sistem kontrol versi Anda, jadi sebaiknya simpan kunci tersebut dalam file secrets.properties, yang terletak di direktori root project Anda. Untuk informasi selengkapnya tentang file secrets.properties, lihat file properti Gradle.

Untuk menyederhanakan tugas ini, sebaiknya gunakan Plugin Secrets Gradle untuk Android.

Catatan: Lihat dokumentasi Plugin Secrets Gradle untuk Android di GitHub guna mengetahui petunjuk penginstalan dan persyaratan sistem terbaru.

Untuk menginstal Plugin Secrets Gradle untuk Android di project Google Maps:

1. Di Android Studio, buka file build.gradle.kts atau build.gradle tingkat teratas dan tambahkan kode berikut ke elemen dependencies di bagian buildscript.

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. Buka file build.gradle.kts atau build.gradle tingkat modul dan tambahkan kode berikut ke elemen plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. Dalam file build.gradle.kts atau build.gradle tingkat modul, pastikan targetSdk dan compileSdk ditetapkan ke 34.
4. Sinkronkan project Anda dengan Gradle.
5. Buka file secrets.properties di direktori tingkat teratas, lalu tambahkan kode berikut. Ganti YOUR_API_KEY dengan kunci API Anda. Simpan kunci Anda dalam file ini karena secrets.properties tidak di-check in ke dalam sistem kontrol versi.
   Catatan: Jika file secrets.properties tidak ada, buat file tersebut di folder yang sama dengan file local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. Buat file local.defaults.properties di direktori tingkat teratas, folder yang sama dengan file secrets.properties, lalu tambahkan kode berikut.

   Catatan: Masukkan kode sebagaimana yang ditampilkan. Jangan ganti DEFAULT_API_KEY dengan Kunci API Anda.

   MAPS_API_KEY=DEFAULT_API_KEY

   File ini ditujukan untuk menyediakan lokasi cadangan Kunci API jika file secrets.properties tidak dapat ditemukan agar build tidak gagal. Build dapat gagal jika Anda meng-clone aplikasi dari sistem kontrol versi yang menghapus secrets.properties dan Anda belum membuat file secrets.properties secara lokal untuk memberikan Kunci API Anda.

7. Di file AndroidManifest.xml, buka com.google.android.geo.API_KEY, lalu perbarui android:value attribute. Jika tag <meta-data> tidak ada, buat tag tersebut sebagai turunan dari tag <application>.

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   Catatan: com.google.android.geo.API_KEY adalah nama metadata yang disarankan untuk kunci API. Kunci dengan nama ini dapat digunakan untuk mengautentikasi beberapa API berbasis Google Maps sekaligus di platform Android, termasuk Maps SDK for Android. Untuk kompatibilitas mundur, API tersebut juga mendukung nama com.google.android.maps.v2.API_KEY. Nama lama ini hanya memungkinkan autentikasi untuk Android Maps API v2. Aplikasi hanya dapat menetapkan salah satu nama metadata kunci API. Jika keduanya ditentukan, API akan menampilkan pengecualian.

8. Di Android Studio, buka file build.gradle.kts atau build.gradle tingkat modul dan edit properti secrets. Jika properti secrets tidak ada, tambahkan.

   Edit properti plugin untuk menetapkan propertiesFileName ke secrets.properties, menetapkan defaultPropertiesFileName ke local.defaults.properties, dan menetapkan properti lainnya.

   Kotlin

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
           

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
           

Lihat kodenya

Periksa kode yang disediakan oleh template. Secara khusus, lihat file berikut di project Android Studio Anda.

File aktivitas Maps

File aktivitas peta adalah aktivitas utama untuk aplikasi, dan berisi kode untuk mengelola dan menampilkan peta. Secara default, file yang menentukan aktivitas diberi nama MapsActivity.java, atau MapsActivity.kt jika Anda menetapkan Kotlin sebagai bahasa aplikasi.

Elemen utama aktivitas Maps:

• Objek SupportMapFragment mengelola siklus proses peta dan merupakan elemen induk dari UI aplikasi.

• Objek GoogleMap memberikan akses ke data dan tampilan peta. Ini adalah class utama Maps SDK for Android. Panduan Objek Peta menjelaskan objek SupportMapFragment dan GoogleMap secara lebih detail.

• Fungsi moveCamera memusatkan peta pada koordinat LatLng untuk Sydney, Australia. Setelan pertama yang dikonfigurasi saat menambahkan peta biasanya adalah lokasi peta dan setelan kamera; seperti sudut pandang, orientasi peta, dan tingkat zoom. Lihat panduan Kamera dan Tampilan untuk mengetahui detailnya.

• Fungsi addMarker menambahkan penanda ke koordinat Sydney. Lihat panduan Penanda untuk mengetahui detailnya.

File Gradle Modul

File build.gradle.kts Modul menyertakan dependensi peta berikut, yang diperlukan oleh Maps SDK for Android.

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Catatan: Versi tepatnya dapat berubah berdasarkan versi Maps SDK for Android saat ini.

Untuk mempelajari cara mengelola dependensi Maps lebih lanjut, lihat Pembuatan versi.

File tata letak XML

File activity_maps.xml adalah file tata letak XML yang menentukan struktur UI aplikasi. File tersebut terletak di direktori res/layout. File activity_maps.xml mendeklarasikan fragmen yang menyertakan elemen-elemen berikut:

• tools:context menetapkan aktivitas default fragmen ke MapsActivity, yang ditentukan dalam file aktivitas peta.
• android:name menetapkan nama class fragmen ke SupportMapFragment, yang merupakan jenis fragmen yang digunakan dalam file aktivitas peta.

File tata letak XML berisi kode berikut:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

Men-deploy dan menjalankan aplikasi

Jika berhasil dijalankan, aplikasi akan menampilkan peta yang berpusat di Sydney, Australia dengan penanda di kota seperti yang terlihat pada screenshot berikut.

Untuk men-deploy dan menjalankan aplikasi:

1. Di Android Studio, klik opsi menu Run (atau ikon tombol putar) untuk menjalankan aplikasi Anda.
2. Jika diminta memilih perangkat, pilih salah satu opsi berikut:
   • Pilih perangkat Android yang terhubung ke komputer Anda.
   • Atau, pilih tombol pilihan Launch emulator dan pilih perangkat virtual yang Anda siapkan.
3. Klik OK. Android Studio akan memulai Gradle untuk membangun aplikasi Anda, lalu menampilkan hasilnya di perangkat atau emulator. Perlu waktu beberapa menit sebelum aplikasi diluncurkan.

Langkah berikutnya

• Menyiapkan peta: Dokumen ini menjelaskan cara menyiapkan setelan awal dan setelan runtime peta, seperti posisi kamera, jenis peta, komponen UI, dan gestur.

• Menambahkan peta ke aplikasi Android (Kotlin): Codelab ini memandu Anda dalam aplikasi dan menunjukkan beberapa fitur tambahan Maps SDK for Android.

• Menggunakan library Android KTX Maps: Library ekstensi Kotlin (KTX) ini memungkinkan Anda memanfaatkan beberapa fitur bahasa Kotlin saat menggunakan Maps SDK for Android.