Panduan Memulai Maps SDK for Android

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

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

Menyiapkan lingkungan pengembangan

  1. Anda perlu memiliki Android Studio. Jika belum punya, download dan instal Android Studio.

  2. Tambahkan SDK layanan Google Play ke Android Studio. Maps SDK for Android didistribusikan sebagai bagian dari SDK layanan Google Play, yang dapat Anda tambahkan melalui SDK Manager.

Menyiapkan perangkat Android

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

Membuat project Google Maps

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

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

  3. Isi formulir Google Maps Activity:

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

    • Setel Minimum SDK ke versi Android SDK yang didukung oleh perangkat pengujian Anda.

  4. Klik Finish.

Setelah selesai membuat project, Android Studio akan memulai Gradle dan mem-build project. Proses ini mungkin berlangsung lama. Setelah proses build selesai, Android Studio akan membuka file google_maps_api.xml dan MapsActivity . Aktivitas Anda mungkin memiliki nama berbeda, tetapi yang akan digunakan adalah nama yang dikonfigurasi selama penyiapan.

Untuk informasi selengkapnya tentang cara membuat project, lihat halaman Membuat Project Android.

File google_maps_api.xml berisi petunjuk cara mendapatkan kunci API Google Maps dan menambahkannya ke file. Jangan tambahkan kunci API Anda ke file. Tindakan tersebut akan menyebabkan penyimpanan kunci API menjadi kurang aman. Sebagai gantinya, ikuti petunjuk di bagian berikutnya.

Penyiapan di Cloud Console

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

Langkah 1

Konsol

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

    Buka halaman pemilih project

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

    Google Cloud menawarkan uji coba gratis senilai $300, dan Google Maps Platform memberikan kredit bulanan berulang senilai $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:

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:

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

    Buka halaman Kredensial

  2. Pada halaman Kredensial, klik Buat kredensial > Kunci API.
    Dialog Kunci API dibuat akan menampilkan kunci API yang baru dibuat.
  3. Klik Tutup.
    Kunci API baru dicantumkan pada halaman Kredensial di bawah Kunci API.
    (Jangan lupa untuk membatasi kunci API sebelum menggunakannya dalam produksi.)

Cloud SDK

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

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

Menambahkan kunci API ke aplikasi

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

Untuk menyederhanakan tugas ini, Anda dapat menggunakan Plugin Secrets Gradle untuk Android.

Untuk menginstal plugin dan menyimpan kunci API Anda:

  1. Di Android Studio, buka file build.gradle tingkat root dan tambahkan kode berikut ke elemen dependencies di bagian buildscript.
    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
        }
    }
        
  2. Selanjutnya, buka file build.gradle tingkat aplikasi dan tambahkan kode berikut ke elemen plugins.
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. Simpan file dan sinkronkan project Anda dengan Gradle.
  4. Buka local.properties pada direktori tingkat project, lalu tambahkan kode berikut. Ganti YOUR_API_KEY dengan kunci API Anda.
    MAPS_API_KEY=YOUR_API_KEY
        
  5. Simpan file dan sinkronkan project Anda dengan Gradle.
  6. Dalam file AndroidManifest.xml Anda, buka com.google.android.geo.API_KEY dan perbarui android:value attribute seperti berikut:
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Catatan: Seperti yang ditunjukkan di atas, 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 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 ditetapkan, API akan memberikan pengecualian.

Melihat kode

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

File aktivitas peta

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 jika Anda menetapkan Kotlin sebagai bahasa aplikasi, diberi nama MapsActivity.kt.

Elemen utama aktivitas peta:

  • 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 aktivitas peta berisi kode berikut:

Java


// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

Kotlin


// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example.kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions
import com.google.maps.example.R

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}

      

File Gradle tingkat aplikasi

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

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.0.0'
    // ...
}

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:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

Men-deploy dan menjalankan aplikasi

Screenshot berisi peta dan penanda yang berada di tengah-tengah Sydney, Australia.

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 mem-build aplikasi Anda, lalu menampilkan hasilnya di perangkat atau emulator. Perlu waktu beberapa menit sebelum aplikasi diluncurkan.

Langkah berikutnya

  • Menyiapkan peta: Topik 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 yang menunjukkan beberapa fitur tambahan Maps SDK for Android.