Menyiapkan project Android Studio

Halaman ini menjelaskan cara mengonfigurasi project Android Studio yang ada untuk menggunakan Maps SDK for Android tanpa menggunakan template Google Maps yang dijelaskan dalam Panduan Memulai.

Template Google Maps akan otomatis mengonfigurasi dan menambahkan peta dasar ke project Android Studio baru. Namun, Anda juga dapat menambahkan peta ke project Android yang menggunakan template Android Studio lain. Untuk melakukannya, Anda harus mengonfigurasi project secara manual, lalu menambahkan peta.

Langkah 1: Siapkan Android Studio

Dokumen ini menjelaskan lingkungan pengembangan yang 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 versi tersebut. Untuk informasi selengkapnya mengenai versi Android Studio dan Gradle, lihat kompatibilitas plugin Android Gradle dan Android Studio.

Langkah 2: Siapkan SDK

Library Maps SDK for Android tersedia melalui repositori Maven Google. Untuk menambahkan SDK ke aplikasi Anda, lakukan hal berikut:

1. Di file settings.gradle tingkat atas, sertakan portal plugin Gradle, repositori Maven Google, dan repositori pusat Maven di bagian blok pluginManagement. Blok pluginManagement harus muncul sebelum pernyataan lain dalam skrip.

   pluginManagement {
       repositories {
           gradlePluginPortal()
           google()
           mavenCentral()
       }
   } 

2. Dalam file settings.gradle tingkat atas, sertakan repositori Maven Google dan repositori pusat Maven di bagian blok dependencyResolutionManagement:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. Dalam file build.gradle tingkat modul, tambahkan dependensi layanan Google Play untuk Maps SDK for Android.

   Groovy

   dependencies {
   
       // Maps SDK for Android
       implementation 'com.google.android.gms:play-services-maps:18.2.0'
   }

   Kotlin

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

4. Dalam file build.gradle tingkat modul, tetapkan compileSdk dan minSdk ke nilai berikut:
   Catatan: Pastikan compileSdk ditetapkan ke 34 atau yang lebih tinggi dan minSdk ditetapkan ke 19 atau lebih tinggi.

   Groovy

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 19
           // ...
       }
   }

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 19
           // ...
       }
   }

5. Di bagian buildFeatures dari file build.gradle tingkat modul, tambahkan class BuildConfig, yang dapat Anda gunakan untuk mengakses nilai metadata yang akan dijelaskan di bawah dalam prosedur ini:

   Groovy

   android {
     // ...
     buildFeatures {
       buildConfig true
       // ...
     }
   }

   Kotlin

   android {
     // ...
     buildFeatures {
       buildConfig = true
       // ...
     }
   }

Langkah 3: Tambahkan kunci API Anda ke project

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 utama 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 atau build.gradle.kts tingkat teratas dan tambahkan kode berikut ke elemen dependencies di bagian buildscript.

   Groovy

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

   Kotlin

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

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

   Groovy

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

   Kotlin

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

3. Di file build.gradle tingkat modul, pastikan targetSdk dan compileSdk ditetapkan ke 34.
4. Simpan file dan 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. Simpan file.

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

8. Simpan file.
9. 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}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

Langkah 4: Perbarui manifes aplikasi

Bagian ini menjelaskan setelan yang akan ditambahkan ke file AndroidManifest.xml.

Nomor versi layanan Google Play

Tambahkan deklarasi berikut dalam elemen application. Tindakan tersebut akan menyematkan versi layanan Google Play yang digunakan untuk mengompilasi aplikasi.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Izin akses lokasi

Jika aplikasi perlu mengakses lokasi pengguna, Anda perlu meminta izin akses lokasi di file AndroidManifest.xml. Opsinya adalah ACCESS_FINE_LOCATION, yang memberikan lokasi presisi perangkat, dan ACCESS_COARSE_LOCATION, yang tidak terlalu presisi. Untuk mengetahui detailnya, lihat panduan data lokasi.

Catatan: Panduan memulai telah mengaktifkan ACCESS_FINE_LOCATION.

Untuk meminta izin ACCESS_FINE_LOCATION, tambahkan kode ini ke elemen manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Izin penyimpanan eksternal

Jika menargetkan SDK layanan Google Play versi 8.3 atau yang lebih baru, Anda tidak memerlukan izin WRITE_EXTERNAL_STORAGE. Jika menargetkan SDK layanan Google Play versi sebelumnya, Anda harus meminta izin WRITE_EXTERNAL_STORAGE, di elemen manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Library Apache HTTP Legacy

Jika Anda menggunakan com.google.android.gms:play-services-maps:16.0.0 atau yang lebih lama dan aplikasi Anda menarget API level 28 (Android 9.0) atau yang lebih tinggi, Anda harus menyertakan deklarasi berikut dalam elemen <application> dari AndroidManifest.xml. Jika tidak, lewati deklarasi ini.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

Langkah 5: Siapkan perangkat Android

Untuk menjalankan aplikasi yang menggunakan Maps SDK for Android, Anda harus men-deploy aplikasi tersebut ke perangkat Android atau emulator Android yang didasarkan pada Android 4.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:

  

Langkah 6: Periksa dukungan Layanan Play jika perlu

Untuk menggunakan Maps SDK for Android, layanan Google Play harus terinstal di perangkat tempat Anda men-deploy aplikasi. Google menyediakan metode yang dapat Anda panggil dari aplikasi untuk memeriksa penginstalan layanan Google Play. Untuk mengetahui informasi lebih lanjut, lihat bagian Memeriksa apakah layanan Google Play terinstal.

Langkah berikutnya

Setelah project dikonfigurasi, Anda dapat menambahkan peta.