Membuat aplikasi navigasi

Halaman ini menjelaskan berbagai fitur Library Aplikasi Mobil yang dapat Anda gunakan untuk menerapkan fungsi aplikasi navigasi belokan demi belokan.

Mendeklarasikan dukungan navigasi dalam manifes Anda

Aplikasi navigasi Anda harus mendeklarasikan kategori aplikasi mobil androidx.car.app.category.NAVIGATION dalam filter intent CarAppService-nya:

<application>
    ...
   <service
       ...
        android:name=".MyNavigationCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.NAVIGATION"/>
      </intent-filter>
    </service>
    ...
</application>

Mendukung intent navigasi

Berbagai format intent memungkinkan aplikasi navigasi berfungsi dengan aplikasi lain, seperti aplikasi lokasi menarik dan asisten suara.

Untuk mendukung format intent ini, pertama-tama deklarasikan dukungan dengan menambahkan filter intent dalam manifes aplikasi Anda. Lokasi filter intent ini bergantung pada platform:

• Android Auto: Dalam elemen manifes <activity> untuk Activity yang digunakan untuk menangani intent saat pengguna tidak menggunakan Android Auto.
• Android Automotive OS: Dalam elemen manifes <activity> untuk CarAppActivity.

Kemudian, baca dan tangani intent dalam callback onCreateScreen() dan onNewIntent() di implementasi Session aplikasi Anda.

Format intent yang diperlukan

Untuk memenuhi persyaratan kualitas NF-6, aplikasi Anda harus menangani intent navigasi.

Format intent opsional

Anda juga dapat mendukung format intent berikut untuk lebih meningkatkan interoperabilitas aplikasi Anda:

• Maksud penelusuran
• Intent tindakan kustom

Mengakses template navigasi

Aplikasi navigasi dapat mengakses template berikut, yang menampilkan platform di latar belakang dengan peta dan, selama navigasi aktif, rute belokan demi belokan.

• NavigationTemplate: Template yang menampilkan pesan informasi opsional dan estimasi perjalanan selama navigasi aktif.
• MapWithContentTemplate: Template yang memungkinkan aplikasi merender petak peta dengan beberapa jenis konten (misalnya, daftar). Konten biasanya dirender sebagai overlay di atas petak peta, dengan peta yang terlihat dan area stabil menyesuaikan dengan konten.

Untuk mengetahui detail selengkapnya tentang cara mendesain antarmuka pengguna aplikasi navigasi menggunakan template ini, lihat Aplikasi navigasi.

Untuk mendapatkan akses ke template navigasi, aplikasi Anda harus mendeklarasikan izin androidx.car.app.NAVIGATION_TEMPLATES di file AndroidManifest.xml-nya:

<manifest ...>
  ...
  <uses-permission android:name="androidx.car.app.NAVIGATION_TEMPLATES"/>
  ...
</manifest>

Izin tambahan diperlukan untuk menggambar peta.

Bermigrasi ke MapWithContentTemplate

Mulai dari Car App API Level 7, the MapTemplate, PlaceListNavigationTemplate, dan RoutePreviewNavigationTemplate tidak digunakan lagi. Template yang tidak digunakan lagi akan terus didukung, tetapi sangat disarankan untuk bermigrasi ke MapWithContentTemplate.

Fungsi yang disediakan oleh template ini dapat diimplementasikan menggunakan MapWithContentTemplate. Lihat cuplikan berikut untuk contohnya:

// MapTemplate (deprecated)
val templateDeprecated = MapTemplate.Builder()
    .setPane(paneBuilder.build())
    .setActionStrip(actionStrip)
    .setHeader(header)
    .setMapController(mapController)
    .build()

// MapWithContentTemplate
val template = MapWithContentTemplate.Builder()
    .setContentTemplate(
        PaneTemplate.Builder(paneBuilder.build())
            .setHeader(header)
            .build()
    )
    .setActionStrip(actionStrip)
    .setMapController(mapController)
    .build()
Navigation.kt

// PlaceListNavigationTemplate (deprecated)
val templateDeprecated = PlaceListNavigationTemplate.Builder()
    .setItemList(itemListBuilder.build())
    .setHeader(header)
    .setActionStrip(actionStrip)
    .setMapActionStrip(mapActionStrip)
    .build()

// MapWithContentTemplate
val template = MapWithContentTemplate.Builder()
    .setContentTemplate(
        ListTemplate.Builder()
            .setSingleList(itemListBuilder.build())
            .setHeader(header)
            .build()
    )
    .setActionStrip(actionStrip)
    .setMapController(
        MapController.Builder()
            .setMapActionStrip(mapActionStrip)
            .build()
    )
    .build()
Navigation.kt

// RoutePreviewNavigationTemplate (deprecated)
val templateDeprecated = RoutePreviewNavigationTemplate.Builder()
    .setItemList(
        ItemList.Builder()
            .addItem(
                Row.Builder()
                    .setTitle(title)
                    .build()
            )
            .build()
    )
    .setHeader(header)
    .setNavigateAction(
        Action.Builder()
            .setTitle(actionTitle)
            .setOnClickListener { /* onClick */ }
            .build()
    )
    .setActionStrip(actionStrip)
    .setMapActionStrip(mapActionStrip)
    .build()

// MapWithContentTemplate
val template = MapWithContentTemplate.Builder()
    .setContentTemplate(
        ListTemplate.Builder()
            .setSingleList(
                ItemList.Builder()
                    .addItem(
                        Row.Builder()
                            .setTitle(title)
                            .addAction(
                                Action.Builder()
                                    .setTitle(actionTitle)
                                    .setOnClickListener { /* onClick */ }
                                    .build()
                            )
                            .build()
                    )
                    .build()
            )
            .setHeader(header)
            .build()
    )
    .setActionStrip(actionStrip)
    .setMapController(
        MapController.Builder()
            .setMapActionStrip(mapActionStrip)
            .build()
    )
    .build()
Navigation.kt

Menyampaikan metadata navigasi

Aplikasi navigasi harus mengomunikasikan metadata navigasi tambahan dengan host. Host menggunakan informasi tersebut untuk menyediakan informasi bagi head unit kendaraan dan untuk mencegah bentrok antar-aplikasi navigasi yang menggunakan resource bersama.

Metadata navigasi disediakan melalui layanan mobil yang dapat diakses dari:NavigationManagerCarContext

val navigationManager = carContext.getCarService(NavigationManager::class.java)
Navigation.kt

Memulai, mengakhiri, dan menghentikan navigasi

Agar dapat mengelola beberapa aplikasi navigasi, notifikasi pemilihan rute, dan data cluster kendaraan, host harus mengetahui status navigasi saat ini. Saat pengguna memulai navigasi, panggil NavigationManager.navigationStarted. Demikian pula, saat navigasi berakhir, misalnya saat pengguna tiba di tujuan atau pengguna membatalkan navigasi, panggil NavigationManager.navigationEnded.

Hanya panggil NavigationManager.navigationEnded saat pengguna selesai menavigasi. Misalnya, jika Anda perlu menghitung ulang rute di tengah perjalanan, gunakan Trip.Builder.setLoading(true) sebagai gantinya.

Terkadang, host memerlukan aplikasi untuk menghentikan navigasi dan memanggil onStopNavigation dalam objek NavigationManagerCallback yang disediakan oleh aplikasi Anda melalui NavigationManager.setNavigationManagerCallback. Aplikasi harus berhenti menampilkan informasi belokan berikutnya dalam tampilan cluster, notifikasi navigasi, dan panduan suara.

Memperbarui informasi perjalanan

Selama navigasi aktif, panggil NavigationManager.updateTrip. Informasi yang diberikan dalam panggilan ini dapat digunakan oleh cluster kendaraan dan heads-up display. Bergantung pada kendaraan tertentu yang dikemudikan, tidak semua informasi ditampilkan kepada pengguna. Misalnya, Head Unit Desktop (DHU) menampilkan yang Step ditambahkan ke Trip, tetapi tidak menampilkan informasi Destination.

Menggambar ke Layar Cluster

Untuk memberikan pengalaman pengguna yang paling imersif, Anda mungkin tidak hanya menampilkan metadata dasar di layar cluster kendaraan. Mulai dari Car App API Level 6, aplikasi navigasi memiliki opsi untuk merender konten mereka sendiri secara langsung di layar cluster (di kendaraan yang didukung), dengan batasan berikut:

• Cluster display API tidak mendukung kontrol input
• Pedoman kualitas aplikasi mobil NF-9: Layar cluster hanya boleh menampilkan kartu peta. Rute navigasi aktif dapat secara opsional ditampilkan di petak ini.
• Cluster display API hanya mendukung penggunaan NavigationTemplate
  • Tidak seperti layar utama, layar cluster mungkin tidak secara konsisten menampilkan semua elemen UI NavigationTemplate, seperti petunjuk belokan demi belokan, kartu PWT, dan tindakan. Petak peta adalah satu-satunya elemen UI yang ditampilkan secara konsisten.

Mendeklarasikan Dukungan Cluster

Untuk memberi tahu aplikasi host bahwa aplikasi Anda mendukung rendering pada layar cluster, Anda harus menambahkan elemen androidx.car.app.category.FEATURE_CLUSTER <category> ke <intent-filter> CarAppService seperti yang ditunjukkan di bagian cuplikan berikut:

<application>
    ...
   <service
       ...
        android:name=".MyNavigationCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.NAVIGATION"/>
        <category android:name="androidx.car.app.category.FEATURE_CLUSTER"/>
      </intent-filter>
    </service>
    ...
</application>

Siklus Proses dan Pengelolaan Status

Mulai API level 6, alur siklus proses aplikasi mobil tetap sama, tetapi sekarang CarAppService::onCreateSession mengambil parameter jenis SessionInfo yang memberikan informasi tambahan tentang Session yang sedang dibuat (yaitu, jenis layar dan kumpulan template yang didukung).

Aplikasi memiliki opsi untuk menggunakan class Session yang sama untuk menangani layar cluster dan layar utama, atau membuat Sessions khusus layar untuk menyesuaikan perilaku pada setiap layar (seperti yang ditunjukkan dalam cuplikan berikut).

override fun onCreateSession(sessionInfo: SessionInfo): Session {
    return if (sessionInfo.displayType == SessionInfo.DISPLAY_TYPE_CLUSTER) {
        ClusterSession()
    } else {
        MainDisplaySession()
    }
}
Navigation.kt

Tidak ada jaminan terkait kapan atau apakah layar cluster akan disediakan. Selain itu, ada kemungkinan Session cluster akan menjadi satu-satunya Session (misalnya, pengguna menukar layar utama ke aplikasi lain saat aplikasi Anda bernavigasi secara aktif). Perjanjian "standar"-nya adalah bahwa aplikasi mendapatkan kontrol layar cluster hanya setelah NavigationManager::navigationStarted dipanggil. Namun, aplikasi dapat menyediakan layar cluster saat tidak ada navigasi aktif yang muncul, atau tidak pernah diberikan layar cluster. Aplikasi Anda dapat menangani skenario ini dengan merender status tidak ada aktivitas pada petak peta aplikasi Anda.

Host membuat binder dan instance CarContext yang terpisah per Session. Artinya, saat menggunakan metode seperti ScreenManager::push atau Screen::invalidate, hanya Session tempat metode tersebut dipanggil yang akan terpengaruh. Aplikasi harus membuat saluran komunikasi sendiri antara instance ini jika komunikasi lintas Session diperlukan (misalnya, dengan menggunakan siaran, singleton bersama, atau lainnya).

Menguji Dukungan Cluster

Anda dapat menguji implementasinya di Android Auto dan Android Automotive OS. Untuk Android Auto, pengujian ini dilakukan dengan mengonfigurasi Desktop Head Unit untuk mengemulasikan layar cluster sekunder. Untuk Android Automotive OS, Generic System Image (GSI) untuk API level 30 dan yang lebih tinggi akan mengemulasikan layar cluster.

Menyesuaikan TravelEstimate dengan teks atau ikon

Untuk menyesuaikan estimasi perjalanan dengan teks, ikon, atau keduanya, gunakan setTripIcon class TravelEstimate.Builder atau metode setTripText. NavigationTemplate menggunakan TravelEstimate untuk menyetel teks dan ikon secara opsional, atau sebagai pengganti perkiraan waktu tiba, waktu tersisa, dan jarak tersisa.

Cuplikan berikut menggunakan setTripIcon dan setTripText untuk menyesuaikan estimasi perjalanan:

TravelEstimate.Builder(
    Distance.create(350.0, Distance.UNIT_METERS),
    arrivalTimeAtDestination
)
    .setTripIcon(
        CarIcon.Builder(
            IconCompat.createWithResource(carContext, R.drawable.ic_garage)
        ).build()
    )
    .setTripText(CarText.create("Custom Text"))
    .build()
Navigation.kt

Menyediakan notifikasi belokan demi belokan

Menyediakan petunjuk navigasi belokan demi belokan (TBT) menggunakan notifikasi navigasi yang sering diperbarui. Agar diperlakukan sebagai notifikasi navigasi di layar mobil, builder notifikasi Anda harus melakukan hal berikut:

1. Tandai notifikasi sebagai sedang berlangsung dengan metode.NotificationCompat.Builder.setOngoing
2. Tetapkan kategori notifikasi ke Notification.CATEGORY_NAVIGATION.
3. Perluas notifikasi dengan CarAppExtender.

Notifikasi navigasi ditampilkan di widget kolom samping di bagian bawah layar mobil. Jika tingkat kepentingan notifikasi disetel ke IMPORTANCE_HIGH, notifikasi juga ditampilkan sebagai notifikasi peringatan dini (HUN). Jika nilai penting tidak ditetapkan dengan metode CarAppExtender.Builder.setImportance, nilai penting saluran notifikasi digunakan.

Aplikasi dapat menyetel PendingIntent di CarAppExtender yang dikirim ke aplikasi saat pengguna mengetuk HUN atau widget kolom samping.

Jika NotificationCompat.Builder.setOnlyAlertOnce dipanggil dengan nilai true, notifikasi dengan nilai penting yang tinggi dikirim hanya sekali di HUN.

Cuplikan berikut ini menunjukkan cara membuat notifikasi navigasi:

NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    .setOnlyAlertOnce(true)
    .setOngoing(true)
    .setCategory(NotificationCompat.CATEGORY_NAVIGATION)
    .extend(
        CarAppExtender.Builder()
            .setContentTitle(carScreenTitle)
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_OPEN_APP.hashCode(),
                    Intent(ACTION_OPEN_APP).setComponent(
                        ComponentName(context, MyNotificationReceiver::class.java)
                    ),
                    PendingIntent.FLAG_IMMUTABLE
                )
            )
            .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH)
            .build()
    )
    .build()
Navigation.kt

Memperbarui notifikasi TBT secara teratur untuk perubahan jarak, yang memperbarui widget kolom samping, dan hanya menampilkan notifikasi sebagai HUN. Anda dapat mengontrol perilaku HUN dengan menetapkan nilai penting notifikasi dengan CarAppExtender.Builder.setImportance. Menetapkan nilai penting ke IMPORTANCE_HIGH akan menampilkan HUN. Menetapkannya ke nilai lain hanya akan memperbarui widget kolom samping.

Memuat ulang konten PlaceListNavigationTemplate

Anda dapat mengizinkan pengemudi memuat ulang konten dengan mengetuk tombol saat menjelajahi daftar tempat yang dibangun dengan PlaceListNavigationTemplate. Untuk mengaktifkan pemuatan ulang daftar, implementasikan metode onContentRefreshRequested antarmuka OnContentRefreshListener, dan gunakan PlaceListNavigationTemplate.Builder.setOnContentRefreshListener untuk menetapkan pemroses pada template.

Cuplikan berikut menunjukkan cara menetapkan pemroses pada template:

PlaceListNavigationTemplate.Builder()
    .setOnContentRefreshListener {
        // Execute any desired logic
        // Then call invalidate() so onGetTemplate() is called again
        screen.invalidate()
    }
    .build()
Navigation.kt

Tombol muat ulang hanya ditampilkan dalam header PlaceListNavigationTemplate jika pemroses memiliki nilai.

Saat pengguna mengklik tombol muat ulang, metode onContentRefreshRequested dari implementasi OnContentRefreshListener Anda akan dipanggil. Dalam onContentRefreshRequested, panggil metode Screen.invalidate. Host kemudian memanggil kembali ke metode Screen.onGetTemplate aplikasi untuk mengambil template dengan konten yang dimuat ulang. Lihat Memuat ulang konten template untuk informasi selengkapnya tentang memuat ulang template. Selama template berikutnya yang ditampilkan oleh onGetTemplate memiliki jenis yang sama, template tersebut dianggap sebagai pemuatan ulang dan tidak dihitung dalam kuota template.

Memberikan panduan audio

Untuk memutar panduan navigasi melalui speaker mobil, aplikasi Anda harus meminta fokus audio. Sebagai bagian dari AudioFocusRequest, setel penggunaan sebagai AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE. Selain itu, tetapkan peningkatan fokus sebagai AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK.

Menyimulasikan navigasi

Untuk memverifikasi fungsi navigasi aplikasi Anda saat mengirimkannya ke Google Play Store, aplikasi Anda harus menerapkan callback NavigationManagerCallback.onAutoDriveEnabled. Saat callback ini dipanggil, aplikasi Anda harus menyimulasikan navigasi ke tujuan yang dipilih saat pengguna memulai navigasi. Aplikasi Anda dapat keluar dari mode ini setiap kali siklus proses Session saat ini mencapai status Lifecycle.Event.ON_DESTROY.

Anda dapat menguji apakah implementasi onAutoDriveEnabled dipanggil dengan menjalankan perintah berikut dari command line:

adb shell dumpsys activity service CAR_APP_SERVICE_NAME AUTO_DRIVE

Hal ini ditunjukkan dalam contoh berikut:

adb shell dumpsys activity service androidx.car.app.samples.navigation.car.NavigationCarAppService AUTO_DRIVE

Aplikasi mobil navigasi default

Di Android Auto, aplikasi mobil navigasi default sesuai dengan aplikasi navigasi terakhir yang diluncurkan pengguna. Aplikasi default menerima intent navigasi saat pengguna memanggil perintah navigasi melalui Asisten atau saat aplikasi lain mengirim intent untuk memulai navigasi.

Menampilkan notifikasi navigasi dalam konteks

Alert menampilkan informasi penting kepada pengemudi dengan tindakan opsional ‐ tanpa keluar dari konteks layar navigasi. Untuk memberikan pengalaman terbaik kepada pengemudi, Alert berfungsi di dalam NavigationTemplate untuk menghindari pemblokiran rute navigasi dan untuk meminimalkan gangguan bagi pengemudi.

Alert hanya tersedia dalam NavigationTemplate. Untuk memberi tahu pengguna di luar NavigationTemplate, pertimbangkan untuk menggunakan notifikasi peringatan dini (HUN) seperti yang dijelaskan dalam Menampilkan notifikasi.

Misalnya, gunakan Alert untuk:

• Memberi tahu pengemudi tentang informasi terbaru yang relevan dengan navigasi saat ini, seperti perubahan kondisi lalu lintas.
• Meminta pengemudi untuk memberikan informasi terbaru terkait navigasi saat ini, seperti adanya alat pengukur kecepatan.
• Mengusulkan tugas mendatang dan menanyakan apakah pengemudi menerimanya, seperti apakah pengemudi bersedia menjemput seseorang dalam perjalanan mereka.

Dalam bentuk dasarnya, Alert terdiri dari judul dan waktu durasi Alert. Waktu durasi direpresentasikan oleh status progres. Jika ingin, Anda dapat menambahkan subtitel, ikon, dan maksimal dua objek Action.

Setelah ditampilkan, Alert tidak akan dibawa ke template lain jika interaksi pengemudi membuat NavigationTemplate ditinggalkan. Data tetap dalam versi NavigationTemplate asli hingga waktu tunggu Alert habis, pengguna mengambil tindakan, atau aplikasi menutup Alert.

Membuat notifikasi

Gunakan Alert.Builder untuk membuat instance Alert:

Alert.Builder(
    1, // alertId
    CarText.create("Hello"), // title
    5000 // durationMillis
)
    // The fields below are optional
    .addAction(firstAction)
    .addAction(secondAction)
    .setSubtitle(CarText.create("Subtitle"))
    .setIcon(CarIcon.APP_ICON)
    .setCallback(alertCallback)
    .build()
Navigation.kt

Jika Anda ingin memproses Alert pembatalan atau penutupan, buat implementasi antarmuka AlertCallback. Jalur panggilan AlertCallback adalah:

• Jika waktu tunggu Alert habis, host akan memanggil metode AlertCallback.onCancel dengan nilai AlertCallback.REASON_TIMEOUT. Kemudian, metode AlertCallback.onDismiss akan dipanggil.

• Jika pengemudi mengklik salah satu tombol tindakan, host akan memanggil Action.OnClickListener lalu memanggil AlertCallback.onDismiss.

• Jika Alert tidak didukung, host akan memanggil AlertCallback.onCancel dengan nilai AlertCallback.REASON_NOT_SUPPORTED. Host tidak memanggil AlertCallback.onDismiss, karena Alert tidak ditampilkan.

Mengonfigurasi durasi notifikasi

Pilih durasi Alert yang sesuai dengan kebutuhan aplikasi Anda. Durasi yang direkomendasikan untuk Alert navigasi adalah 10 detik. Lihat Notifikasi navigasi untuk informasi selengkapnya.

Menampilkan notifikasi

Untuk menampilkan Alert, panggil metode AppManager.showAlert yang tersedia melalui CarContextaplikasi Anda.

carContext.getCarService(AppManager::class.java).showAlert(alert)
Navigation.kt

• Memanggil showAlert dengan Alert yang memiliki alertId yang sama dengan ID Alert yang sudah ditampilkan, tidak akan mengakibatkan apa pun. Alert tidak diperbarui. Untuk mengupdate Alert, Anda harus membuatnya ulang dengan alertId baru.
• Memanggil showAlert dengan Alert yang memiliki alertId berbeda dengan Alert yang sudah ditampilkan akan menutup Alert yang ditampilkan.

Menutup notifikasi

Meskipun Alert otomatis ditutup karena waktu tunggu habis atau interaksi pengemudi, Anda juga dapat menutup Alert secara manual, seperti jika informasinya sudah tidak berlaku. Untuk menutup Alert, panggil dismissAlert metode dengan alertId dari Alert.

carContext.getCarService(AppManager::class.java).dismissAlert(alert.id)
Navigation.kt

Memanggil dismissAlert dengan alertId yang tidak cocok dengan Alert yang sudah ditampilkan, tidak akan mengakibatkan apa pun. Perintah ini tidak memberikan pengecualian.