Menambahkan peta 3D ke aplikasi

Produk atau fitur ini bersifat Eksperimental (pra-GA). Produk dan fitur pra-GA mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Penawaran Pra-GA tercakup dalam Persyaratan Khusus Layanan Google Maps Platform. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Pilih platform: Android iOS JavaScript

Halaman ini membahas contoh cara menambahkan peta 3D dasar ke aplikasi Android menggunakan Maps 3D SDK for Android. Petunjuk di halaman ini mengasumsikan bahwa Anda telah menyelesaikan langkah-langkah di halaman Penyiapan dan memiliki hal berikut:

• Project Google Cloud dengan Maps 3D SDK for Android diaktifkan
• Kunci API yang dikonfigurasi untuk digunakan dengan Maps 3D SDK for Android
• Project Android Studio yang disiapkan untuk digunakan dengan Maps 3D SDK for Android

Untuk mengetahui informasi selengkapnya tentang prasyarat ini, lihat Penyiapan.

Bagian 1: Memperbarui File Tata Letak (activity_main.xml) untuk menambahkan komponen Map3DView

Komponen Map3DView adalah tampilan yang merender peta 3D dalam aplikasi. Langkah-langkah berikut menambahkan komponen dan mengonfigurasi status awal peta, termasuk posisi kamera dan atribut terkait:

Catatan: Langkah-langkah di bagian ini mengasumsikan bahwa Anda telah membuat dan mengonfigurasi project Android Studio menggunakan proses yang dijelaskan di Penyiapan, atau bahwa Anda telah menambahkan aktivitas Tampilan baru ke project yang ada. Jika Anda membuat project Android Studio baru tanpa menambahkan aktivitas Tampilan, project Anda tidak akan berisi file activity_main.xml.

1. Buka file tata letak aktivitas utama Anda, yang biasanya terletak di app/src/main/res/layout/activity_main.xml.

2. Di ConstraintLayout root (atau elemen tata letak root), tambahkan namespace XML map3d:

   xmlns:map3d="http://schemas.android.com/apk/res-auto"
   

3. Hapus <TextView> default yang menampilkan "Hello World!".

4. Tambahkan komponen Map3DView ke tata letak Anda. Anda dapat menyesuaikan posisi kamera dan atribut lainnya:

   <?xml version="1.0" encoding="utf-8"?>
   <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
     android:id="@+id/main"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     tools:context=".MainActivity">
   
     <com.google.android.gms.maps3d.Map3DView
       android:id="@+id/map3dView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       map3d:mode="hybrid"
       map3d:centerLat="38.544012"
       map3d:centerLng="-107.670428"
       map3d:centerAlt="2427.6"
       map3d:heading="310"
       map3d:tilt="63"
       map3d:range="8266"
       map3d:roll="0"
       map3d:minAltitude="0"
       map3d:maxAltitude="1000000"
       map3d:minHeading="0"
       map3d:maxHeading="360"
       map3d:minTilt="0"
       map3d:maxTilt="90"
       app:layout_constraintBottom_toBottomOf="parent"
       app:layout_constraintEnd_toEndOf="parent"
       app:layout_constraintStart_toStartOf="parent"
       app:layout_constraintTop_toTopOf="parent" />
   </androidx.constraintlayout.widget.ConstraintLayout>
   

Bagian 2: Memperbarui MainActivity.kt

Langkah-langkah berikut menginisialisasi komponen Map3DView yang ditambahkan ke file activity_main.xml di Bagian 1 dan mengelola peristiwa siklus proses komponen.

Perhatikan bahwa Maps 3D SDK for Android hanya mendukung satu instance Map3DView aktif dalam satu waktu. Menampilkan beberapa instance Map3DView secara bersamaan (misalnya, dalam tata letak yang sama atau Aktivitas atau Fragmen yang terlihat berbeda) tidak didukung dan dapat menyebabkan masalah rendering, seperti layar hitam pada tampilan sekunder.

Selain itu, semua Map3DView akan berbagi dan mencerminkan status peta yang sama (misalnya, posisi kamera, penanda yang ditambahkan, poligon, dll.), yang akan tetap ada meskipun satu Map3DView dihancurkan (menggunakan onDestroy) dan yang lain dibuat, kecuali jika dihapus secara manual. Misalnya, jika Anda menambahkan penanda ke Map3DView1, lalu menghancurkannya dan membuat Map3DView2, penanda yang sama tersebut akan tetap ada di Map3DView2.

Tanggung Jawab Developer:

• Satu tampilan dalam satu waktu: Pastikan hanya satu Map3DView yang berada di bagian aktif hierarki tampilan Anda kapan saja.
• Pembersihan manual: Saat beralih dari satu Map3DView (misalnya, Map3DView1) ke yang lain (misalnya, Map3DView2), Anda harus memanggil onDestroy() pada instance lama (Map3DView1). Karena status peta yang mendasarinya dibagikan, untuk memastikan Map3DView2 dimulai dengan status baru atau tertentu, Anda bertanggung jawab untuk menghapus secara manual status apa pun yang ditetapkan oleh Map3DView1. Hal ini mencakup menghapus penanda, overlay, dll., dan mereset posisi kamera menggunakan objek GoogleMap3D yang diperoleh di OnMap3DViewReadyCallback.

1. Buka file MainActivity.kt, yang biasanya terletak di app/src/main/java/com/example/yourpackagename/MainActivity.kt.

2. Tambahkan impor yang diperlukan untuk Maps 3D SDK for Android:

   import com.google.android.gms.maps3d.GoogleMap3D
   import com.google.android.gms.maps3d.Map3DView
   import com.google.android.gms.maps3d.OnMap3DViewReadyCallback
   

3. Ubah class MainActivity untuk menerapkan OnMap3DViewReadyCallback:

   class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
   

4. Deklarasikan variabel untuk Map3DView dan GoogleMap3D:

   private lateinit var map3DView: Map3DView
   private var googleMap3D: GoogleMap3D? = null
   

5. Dalam metode onCreate, setelah setContentView(...) dan blok ViewCompat.setOnApplyWindowInsetsListener, inisialisasi map3DView, panggil metode siklus proses onCreate, dan minta peta secara asinkron:

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       enableEdgeToEdge()
       setContentView(R.layout.activity_main)
       ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
           val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
           v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
           insets
       }
   
       map3DView = findViewById(R.id.map3dView)
       map3DView.onCreate(savedInstanceState)
       map3DView.getMap3DViewAsync(this)
   }
   

6. Ganti metode onMap3DViewReady. Callback ini dipicu saat peta siap digunakan:

   override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
       // Interact with the googleMap3D object here
       this.googleMap3D = googleMap3D
       // You can now make calls to the googleMap3D object, e.g.,
       // googleMap3D.cameraController.flyTo(camera { ... })
   }
   

7. Teruskan peristiwa siklus proses dari Aktivitas Anda ke Map3DView dengan menambahkan penggantian berikut ke MainActivity:

   override fun onStart() {
       super.onStart()
       map3DView.onStart()
   }
   
   override fun onResume() {
       super.onResume()
       map3DView.onResume()
   }
   
   override fun onPause() {
       map3DView.onPause()
       super.onPause()
   }
   
   override fun onStop() {
       map3DView.onStop()
       super.onStop()
   }
   
   override fun onDestroy() {
       map3DView.onDestroy()
       super.onDestroy()
   }
   
   override fun onSaveInstanceState(outState: Bundle) {
       super.onSaveInstanceState(outState)
       map3DView.onSaveInstanceState(outState)
   }
   
   override fun onLowMemory() {
       super.onLowMemory()
       map3DView.onLowMemory()
   }
   

Bagian 3: Menyinkronkan Gradle dan Menjalankan

Setelah memperbarui tata letak dan aktivitas aplikasi, Anda dapat mem-build dan menjalankan aplikasi untuk melihat tampilan peta 3D.

1. Untuk menyinkronkan project dengan Gradle, pilih File > Sync Project with Gradle Files.

2. Untuk mem-build dan menjalankan aplikasi di emulator atau perangkat fisik, pilih Run > Run.

Jika semuanya dikonfigurasi dengan benar, Anda akan melihat peta 3D yang ditampilkan di aplikasi, yang berpusat di dekat koordinat yang ditentukan di activity_main.xml.

Langkah berikutnya

Setelah menambahkan peta 3D dasar ke aplikasi, Anda dapat menjelajahi fitur Maps 3D SDK for Android yang lebih canggih, seperti animasi jalur kamera, penanda 3D, atau poligon.

Memproses peristiwa klik peta

Untuk memproses peristiwa klik di peta, gunakan GoogleMap3D.setMap3DClickListener. Pemroses ini dipicu saat pengguna mengklik peta, dan memberikan lokasi serta ID tempat dari titik yang diklik.

Contoh berikut menunjukkan cara menetapkan pemroses klik peta:

googleMap3D.setMap3DClickListener { location, placeId ->
    lifecycleScope.launch(Dispatchers.Main) {
        if (placeId != null) {
            Toast.makeText(this@MainActivity, "Clicked on place with ID: $placeId", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this@MainActivity, "Clicked on location: $location", Toast.LENGTH_SHORT).show()
        }
    }
}

Perhatikan bahwa pengendali klik tidak berjalan di thread Utama (atau UI). Jika ingin melakukan perubahan pada UI (seperti menampilkan pesan Toast), Anda harus beralih ke thread Utama. Untuk Kotlin, Anda dapat melakukannya menggunakan lifecycleScope.launch(Dispatchers.Main).