Panduan Migrasi

Peringatan: Dokumen ini mungkin berisi informasi yang sudah tidak berlaku. Kami sedang berupaya menyelesaikan hal ini, tetapi sebaiknya Anda melihat halaman Memulai untuk sementara guna melihat aplikasi contoh kami. Template ini menampilkan perilaku dan pola penggunaan API yang membantu Anda melakukan migrasi dari v1.

Perubahan terbesar yang dilakukan Google pada Navigation SDK untuk v2 adalah bahwa kami mengganti beberapa class Navigation SDK dengan padanannya dari Maps SDK for Android.

Mulai versi 2.2, Navigation SDK adalah (hampir) pengganti langsung untuk Google Play Services Maps API. Daripada memaketkan ulang semua API ke dalam com.google.android.libraries.maps, API tersebut telah dikemas dalam com.google.android.gms.maps seperti Layanan Google Play. Hal ini menjadikan peralihan antara versi Layanan Google Play dan Navigation SDK jauh lebih sederhana.

Peringatan: Petunjuk ini hanya berlaku untuk versi 2.2 dan yang lebih baru.

Manfaat

• Penggunaan memori yang lebih baik. Sekarang Anda menggunakan lebih sedikit memori dan bandwidth dibandingkan jika menggunakan Navigation SDK dan Maps SDK for Android.
• Beralih dari mode tampilan peta ke mode navigasi kini lebih lancar dan lebih mudah digunakan.
• Anda kini memiliki kontrol kamera yang lebih besar.
• Anda kini dapat melakukan hal-hal seperti menggambar polyline dan overlay, serta menambahkan gaya kustom ke peta.

Namun, fitur seperti Street View dan Mode Ringan tidak didukung.

Poin Penting: Navigation SDK akan menggantikan Maps SDK for Android dan Anda harus menghapus semua referensi ke klien.

Prasyarat

• Navigation SDK versi 2 menggunakan Android Jetpack—serangkaian library, alat, dan panduan yang mempermudah penulisan aplikasi berkualitas tinggi. Langkah ini berarti Anda harus memigrasikan aplikasi dari penggunaan support library untuk menggunakan AndroidX. Untuk informasi selengkapnya, lihat Bermigrasi ke AndroidX.

Langkah 1. Bermigrasi dari Maps SDK for Android

Sebagian besar fungsi di Maps SDK for Android kini disertakan dalam Navigation SDK versi 2. Beberapa fitur dihapus karena tidak diperlukan dalam konteks navigasi.

Perbedaan penting

Maps SDK for Android ada di Layanan Google Play.

Fitur Maps SDK for Android yang dipaketkan dalam Navigation SDK v2 didasarkan pada Maps SDK for Android versi baru, dan tidak ada di Layanan Google Play. Fitur baru ini berjalan di mesin yang lebih baru daripada yang ada di Layanan Google Play, dan memiliki beberapa peningkatan. Artinya, peta tersebut juga berjalan dalam proses aplikasi Anda, bukan dalam proses Layanan Google Play.

Beberapa kelas diganti namanya

Tabel berikut mencantumkan class yang diganti namanya. Hal ini dilakukan untuk membedakannya dari versi Maps SDK for Android.

Nama Class Maps SDK for Android	Nama Class Navigation SDK
MapView.java	NavigationView.java
MapFragment.java	SupportNavigationFragment.java

Class ini berisi gabungan metode yang tersedia di class NavigationView lama, dan class MapView saat ini. Anda dapat menganggapnya seperti class MapView dan MapFragment, tetapi dengan dukungan navigasi.

Fitur yang dihapus

Beberapa fitur Maps dihapus karena tidak relevan dalam konteks navigasi, atau karena adanya inkompatibilitas teknis. Fitur yang dihapus mencakup:

• Street View.
• Mode ringan, yang tidak cukup untuk navigasi.
• Anda tidak dapat menyetel LocationProvider saat kamera berada dalam Mode ikuti. Hal ini karena navigasi bergantung pada RoadSnappedLocationProvider, dan beralih ke penyedia ini dapat menyebabkan masalah saat bernavigasi.
• Menerapkan batas zoom Min/Max dan LatLng tidak akan berpengaruh saat kamera dalam Mode Ikuti.
• Harap hubungi perwakilan pelanggan Anda jika fitur yang hilang ini menyebabkan kesulitan bagi Anda.

Langkah migrasi

1. Hapus integrasi Maps SDK for Android dari build Anda (yaitu gradle). Memiliki kedua SDK akan menyebabkan error kompilasi.
2. Ganti instance MapView dengan instance NavigationView.
3. Ganti instance MapFragment dengan instance NavigationSupportFragment.

Jika aplikasi Anda sebelumnya tidak menggunakan Navigation SDK, berarti migrasi Anda telah selesai.

Langkah 2: Bermigrasi dari v1.x Navigation SDK

Lakukan langkah-langkah berikut untuk memigrasikan integrasi Navigation SDK v1.x ke v2.

1. Mendapatkan peta menggunakan metode baru

Cara Anda mendapatkan peta telah berubah. Sebelum v2, Anda mendapatkan peta dengan menggunakan panggilan sinkron. Sekarang, Anda akan menggunakan panggilan asinkron. Tabel berikut mencantumkan metode lama beserta metode baru untuk mendapatkan peta.

Metode Lama	Metode Baru
NavigationView.getMap()	NavigationView.getMapAsync()
SupportNavigationFragment.getMap()	SupportNavigationFragment.getMapAsync()

Catatan: Class NavigationFragment dihapus karena class Fragment tidak digunakan lagi dan digantikan dengan class SupportFragment.

2. Memigrasikan library

Navigation SDK v1.x berisi penerapannya sendiri untuk beberapa class Maps SDK for Android. Class ini termasuk dalam paket com.google.android.libraries.navigation.

Di v2, class ini telah diganti dengan implementasi Maps SDK for Android, yang berada dalam paket com.google.android.gms.maps.model. Anda dapat memigrasikan aplikasi untuk mengintegrasikan class baru dengan melakukan penelusuran dan penggantian.

Tabel berikut mencantumkan class lama beserta class baru.

Kelas Lama	Kelas Baru
com.google.android.libraries.navigation.LatLng	com.google.android.gms.maps.model.LatLng
com.google.android.libraries.navigation.LatLngBounds	com.google.android.gms.maps.model.LatLngBounds
com.google.android.libraries.navigation.Marker	com.google.android.gms.maps.model.Marker
com.google.android.libraries.navigation.MarkerOptions	com.google.android.gms.maps.model.MarkerOptions
com.google.android.libraries.navigation.VisibleRegion	com.google.android.gms.maps.model.VisibleRegion

3. Mengakomodasi perubahan pada API yang ada

Tabel berikut mencantumkan perubahan penting yang dibuat Google untuk Navigation SDK v2.

Metode	Transfer
NavigationApi.cleanup()	Dihapus. Metode ini tidak digunakan untuk operasi normal, dan dapat menyebabkan perilaku yang tidak dapat diprediksi. Anda harus menghapus panggilan ke metode ini.
RoadSnappedLocationProvider.requestLocationUpdates()	Dihapus. Sebagai gantinya, gunakan addLocationListener().
RoadSnappedLocationProvider.stopRequestingLocationUpdates()	Dihapus. Sebagai gantinya, gunakan removeLocationListener().

4. Mengubah ke class Marker baru

Navigation SDK v2 kini menggunakan implementasi class Marker yang sama seperti Maps SDK for Android. Tindakan ini memperkenalkan perubahan berikut.

Metode terkait penanda

Metode	Transfer
addMarker(MarkerOptions markerOptions)	Sekarang menggunakan class com.google.android.gms.maps.model.MarkerOptions.
removeMarker(Marker marker)	Metode ini sudah tidak ada lagi. Sebagai gantinya, class Marker kini memiliki metode marker.remove().
removeAllMarkers()	Metode ini sudah tidak ada lagi, meskipun ada metode clear() yang menghapus semua penanda, polyline, poligon, dan overlay dari peta.

Perbedaan MarkerOptions

• Metode describeContents() tidak ada di Navigation SDK v2. Ini memungkinkan Anda menyimpan data tampilan dengan memanggil onSaveInstanceState(). Sekarang, Anda harus melacak sendiri detail tampilan agar dapat merekonstruksi tampilan saat ada perubahan konfigurasi.
• Metode navMarker#icon(BitMap) telah berubah menjadi mapMarker#icon(BitmapDescriptor). Perubahan ini mengharuskan Anda bermigrasi dari menggunakan BitMap untuk menggunakan BitmapDescriptor.

Metode penanda

Sekarang Anda akan menggunakan class Marker dari paket com.google.android.gms.maps.model. Tabel berikut mencantumkan perbedaan dalam menggunakan class Marker baru ini.

Metode	Transfer
getAnchorU()	Sudah tidak ada.
getAnchorV()	Sudah tidak ada.
getIcon()	Tidak ada lagi. Anda harus mempertahankan sendiri referensi ke ikon, untuk digunakan setelah perubahan konfigurasi, saat Anda perlu membuat ulang status peta.
getPosition()	Masih ada.
getTitle()	Masih ada.

Catatan: Jika Anda memerlukan metode yang dihapus pada class Penanda, beri tahu kami agar kami dapat membantu menyelesaikan masalah Anda.

5. Kontrol kamera

Kontrol kamera yang disediakan di Navigation SDK v1.x relatif terbatas. Navigation SDK versi 2 kini menggunakan model kamera yang sama dengan yang digunakan oleh Maps SDK for Android, kecuali Anda juga mendapatkan Follow Mode yang mirip dengan yang ada di Navigation SDK v1.x.

Perbedaan utama

• Class com.google.android.libraries.navigation.Camera telah dihapus di v2.
  • Camera.showRouteOverview() dipindahkan ke NavigationView dan SupportNavigationFragment.
  • Metode Camera.followMyLocation() dipindahkan ke GoogleMap.
• Anda dapat mengganti panggilan ke Camera.setLocation() dengan GoogleMap.moveCamera() atau GoogleMap.animateCamera().
• setOnFollowMyLocationCallback() dan isCameraFollowingMyLocation() telah ditambahkan ke GoogleMap untuk memberikan informasi selengkapnya tentang mode berikut.

Langkah 3. Menggabungkan alur aktivitas

Jika sebelumnya Anda menggunakan Navigation SDK V1 dan mengikuti petunjuk di atas, berarti Anda telah memigrasikan kasus penggunaan peta untuk menggunakan class NavigationView, dan telah memigrasikan kasus penggunaan navigasi untuk menggunakan GoogleMap. Namun, Anda akan memiliki dua instance GoogleMap, dan dua instance NavigationView. Artinya, Anda akan tetap menggunakan lebih banyak memori daripada yang diperlukan, dan peralihan antara dua instance tersebut dapat mengakibatkan jeda yang terlihat dalam proses rendering antarmuka pengguna yang lancar. Untuk mengatasi masalah ini, Anda harus menggabungkan alur aktivitas/fragmen agar dapat berbagi satu instance. Hal ini akan memberikan pengalaman pengguna yang lebih lancar dan menyederhanakan aplikasi Anda.