Asisten Google memungkinkan Anda menggunakan perintah suara untuk mengontrol banyak perangkat, seperti Google Home, ponsel, dan lainnya. Layanan ini memiliki kemampuan bawaan untuk memahami perintah media ("putar lagu dari Beyoncé") dan mendukung kontrol media (seperti jeda, lewati, maju cepat, suka).
Asisten berkomunikasi dengan aplikasi media Android menggunakan sesi media. Aplikasi ini dapat menggunakan intent atau layanan untuk meluncurkan aplikasi dan memulai pemutaran. Untuk hasil terbaik, aplikasi Anda harus menerapkan semua fitur yang dijelaskan di halaman ini.
Menggunakan sesi media
Setiap aplikasi audio dan video harus mengimplementasikan sesi media sehingga Asisten dapat mengoperasikan kontrol transport setelah pemutaran dimulai.
Perhatikan bahwa meskipun Asisten hanya menggunakan tindakan yang tercantum di bagian ini, praktik terbaiknya adalah mengimplementasikan semua API persiapan dan pemutaran untuk memastikan
kompatibilitas dengan aplikasi lain. Untuk tindakan apa pun yang tidak Anda dukung,
callback sesi media dapat menampilkan error menggunakan
ERROR_CODE_NOT_SUPPORTED
.
Aktifkan kontrol media dan transport dengan menetapkan flag ini di objek
MediaSession
aplikasi Anda:
Kotlin
session.setFlags( MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS or MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS )
Java
session.setFlags(MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS | MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS);
Sesi media aplikasi Anda harus mendeklarasikan tindakan yang didukungnya, dan mengimplementasikan
callback sesi media yang sesuai. Deklarasikan tindakan yang didukung di
setActions()
.
Project contoh Universal Android Music Player adalah contoh yang baik tentang cara menyiapkan sesi media.
Tindakan pemutaran
Agar dapat memulai pemutaran dari layanan, sesi media harus menerapkan tindakan PLAY
ini dan callback-nya:
Tindakan | Callback |
---|---|
ACTION_PLAY |
onPlay() |
ACTION_PLAY_FROM_SEARCH |
onPlayFromSearch() |
ACTION_PLAY_FROM_URI (*) |
onPlayFromUri() |
Sesi Anda juga harus menerapkan tindakan PREPARE
ini dan callback-nya:
Tindakan | Callback |
---|---|
ACTION_PREPARE |
onPrepare() |
ACTION_PREPARE_FROM_SEARCH |
onPrepareFromSearch() |
ACTION_PREPARE_FROM_URI (*) |
onPrepareFromUri() |
Dengan mengimplementasikan API persiapan, latensi pemutaran setelah perintah suara dapat dikurangi. Aplikasi media yang ingin meningkatkan latensi pemutaran dapat menggunakan waktu tambahan untuk mulai meng-cache konten dan menyiapkan pemutaran media.
Mengurai kueri penelusuran
Saat pengguna menelusuri item media tertentu, seperti “Putar jazz di
[nama aplikasi Anda]” atau “Dengarkan [judul lagu]”, metode callback
onPrepareFromSearch()
atau
onPlayFromSearch()
akan menerima parameter kueri dan paket tambahan.
Aplikasi Anda harus mengurai kueri penelusuran suara dan memulai pemutaran dengan mengikuti langkah-langkah berikut:
- Gunakan paket tambahan dan string kueri penelusuran yang ditampilkan dari penelusuran suara untuk memfilter hasil.
- Buat antrean pemutaran berdasarkan hasil ini.
- Putar item media yang paling relevan dari hasil.
Metode onPlayFromSearch()
mengambil parameter tambahan yang berisi informasi yang lebih mendetail dari penelusuran
suara. Parameter tambahan ini membantu Anda menemukan konten audio di aplikasi Anda untuk diputar.
Jika hasil penelusuran tidak dapat menyediakan data ini, Anda dapat menerapkan logika
untuk mengurai kueri penelusuran mentah dan memutar jalur yang sesuai berdasarkan
kueri.
Parameter tambahan berikut didukung di Android Automotive OS dan Android Auto:
Cuplikan kode berikut menunjukkan cara mengganti metode onPlayFromSearch()
dalam implementasi MediaSession.Callback
Anda untuk mengurai kueri penelusuran suara dan memulai pemutaran:
Kotlin
override fun onPlayFromSearch(query: String?, extras: Bundle?) { if (query.isNullOrEmpty()) { // The user provided generic string e.g. 'Play music' // Build appropriate playlist queue } else { // Build a queue based on songs that match "query" or "extras" param val mediaFocus: String? = extras?.getString(MediaStore.EXTRA_MEDIA_FOCUS) if (mediaFocus == MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) { isArtistFocus = true artist = extras.getString(MediaStore.EXTRA_MEDIA_ARTIST) } else if (mediaFocus == MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) { isAlbumFocus = true album = extras.getString(MediaStore.EXTRA_MEDIA_ALBUM) } // Implement additional "extras" param filtering } // Implement your logic to retrieve the queue var result: String? = when { isArtistFocus -> artist?.also { searchMusicByArtist(it) } isAlbumFocus -> album?.also { searchMusicByAlbum(it) } else -> null } result = result ?: run { // No focus found, search by query for song title query?.also { searchMusicBySongTitle(it) } } if (result?.isNotEmpty() == true) { // Immediately start playing from the beginning of the search results // Implement your logic to start playing music playMusic(result) } else { // Handle no queue found. Stop playing if the app // is currently playing a song } }
Java
@Override public void onPlayFromSearch(String query, Bundle extras) { if (TextUtils.isEmpty(query)) { // The user provided generic string e.g. 'Play music' // Build appropriate playlist queue } else { // Build a queue based on songs that match "query" or "extras" param String mediaFocus = extras.getString(MediaStore.EXTRA_MEDIA_FOCUS); if (TextUtils.equals(mediaFocus, MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE)) { isArtistFocus = true; artist = extras.getString(MediaStore.EXTRA_MEDIA_ARTIST); } else if (TextUtils.equals(mediaFocus, MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE)) { isAlbumFocus = true; album = extras.getString(MediaStore.EXTRA_MEDIA_ALBUM); } // Implement additional "extras" param filtering } // Implement your logic to retrieve the queue if (isArtistFocus) { result = searchMusicByArtist(artist); } else if (isAlbumFocus) { result = searchMusicByAlbum(album); } if (result == null) { // No focus found, search by query for song title result = searchMusicBySongTitle(query); } if (result != null && !result.isEmpty()) { // Immediately start playing from the beginning of the search results // Implement your logic to start playing music playMusic(result); } else { // Handle no queue found. Stop playing if the app // is currently playing a song } }
Untuk contoh yang lebih detail tentang cara menerapkan penelusuran suara untuk memutar konten audio di aplikasi Anda, lihat contoh Universal Android Music Player.
Menangani kueri kosong
Jika onPrepare()
, onPlay()
, onPrepareFromSearch()
, atau onPlayFromSearch()
dipanggil tanpa kueri penelusuran, aplikasi media Anda akan memutar media "saat ini". Jika tidak ada media saat ini, aplikasi harus mencoba memutar sesuatu, seperti
lagu dari playlist terbaru atau antrean acak. Asisten menggunakan
API ini saat pengguna meminta “Putar musik di [nama aplikasi Anda]” tanpa
informasi tambahan.
Saat pengguna mengucapkan “Putar musik di [nama aplikasi Anda]”, Android Automotive OS atau
Android Auto akan mencoba meluncurkan aplikasi Anda dan memutar audio dengan memanggil metode onPlayFromSearch()
aplikasi Anda. Namun, karena pengguna tidak menyebutkan nama item media, metode onPlayFromSearch()
akan menerima parameter kueri kosong. Dalam hal ini, aplikasi harus
merespons dengan langsung memutar audio, seperti lagu dari playlist
terbaru atau antrean acak.
Mendeklarasikan dukungan lama untuk voice action
Pada umumnya, menangani tindakan pemutaran yang dijelaskan di atas akan memberi aplikasi Anda semua fungsi pemutaran yang diperlukan. Namun, beberapa sistem mengharuskan aplikasi Anda berisi filter Intent untuk penelusuran. Anda harus mendeklarasikan dukungan untuk filter Intent ini dalam file manifes aplikasi.
Sertakan kode ini dalam file manifes untuk aplikasi ponsel:
<activity>
<intent-filter>
<action android:name=
"android.media.action.MEDIA_PLAY_FROM_SEARCH" />
<category android:name=
"android.intent.category.DEFAULT" />
</intent-filter>
</activity>
Kontrol transport
Setelah sesi media aplikasi Anda aktif, Asisten dapat memberikan perintah suara untuk mengontrol pemutaran dan memperbarui metadata media. Agar hal ini berfungsi, kode Anda harus mengaktifkan tindakan berikut dan menerapkan callback yang sesuai:
Tindakan | Callback | Deskripsi |
---|---|---|
ACTION_SKIP_TO_NEXT |
onSkipToNext() |
Video berikutnya |
ACTION_SKIP_TO_PREVIOUS |
onSkipToPrevious() |
Lagu sebelumnya |
ACTION_PAUSE, ACTION_PLAY_PAUSE |
onPause() |
Jeda |
ACTION_STOP |
onStop() |
Hentikan |
ACTION_PLAY |
onPlay() |
Lanjutkan |
ACTION_SEEK_TO |
onSeekTo() |
Mundur 30 detik |
ACTION_SET_RATING |
onSetRating(android.support.v4.media.RatingCompat) |
Sukai/Tidak sukai. |
ACTION_SET_CAPTIONING_ENABLED |
onSetCaptioningEnabled(boolean) |
Mengaktifkan atau menonaktifkan teks. |
Perhatikan:
- Agar perintah mencari berfungsi,
PlaybackState
harus diperbarui denganstate, position, playback speed, and update time
. Aplikasi harus memanggilsetPlaybackState()
saat status berubah. - Aplikasi media juga harus menjaga agar metadata sesi media selalu terbaru. Ini mendukung pertanyaan seperti "lagu apa yang sedang diputar?" Aplikasi harus memanggil
setMetadata()
jika kolom yang berlaku (seperti judul lagu, artis, dan nama) berubah. MediaSession.setRatingType()
harus ditetapkan untuk menunjukkan jenis rating yang didukung aplikasi, dan aplikasi harus menerapkanonSetRating()
. Jika tidak mendukung rating, aplikasi harus menetapkan jenis rating keRATING_NONE
.
Voice action yang Anda dukung mungkin akan bervariasi menurut jenis konten.
Jenis Konten | Tindakan yang Diperlukan |
---|---|
Musik |
Harus mendukung: Putar, Jeda, Berhenti, Lewati ke Berikutnya, dan Lewati ke Sebelumnya Sangat merekomendasikan dukungan untuk: Cari ke |
Podcast |
Harus didukung: Putar, Jeda, Berhenti, dan Cari Merekomendasikan dukungan untuk: Lewati ke Berikutnya dan Lewati ke Sebelumnya |
Buku audio | Harus didukung: Putar, Jeda, Berhenti, dan Cari |
Radio | Harus didukung: Putar, Jeda, dan Berhenti |
Berita | Harus mendukung: Putar, Jeda, Berhenti, Lewati ke Berikutnya, dan Lewati ke Sebelumnya |
Video |
Harus didukung: Putar, Jeda, Berhenti, Cari ke, Mundur, dan Maju Cepat Sangat merekomendasikan dukungan untuk: Lewati ke Berikutnya dan Lewati ke Sebelumnya |
Anda harus mendukung sebanyak mungkin tindakan yang tercantum di atas sesuai yang diizinkan penawaran produk Anda, tetapi tetap merespons tindakan lainnya dengan baik. Misalnya, jika hanya pengguna premium yang dapat kembali ke item sebelumnya, Anda mungkin akan mengalami error jika pengguna paket gratis meminta Asisten untuk kembali ke item sebelumnya. Lihat bagian penanganan error untuk panduan selengkapnya.
Contoh kueri suara untuk dicoba
Tabel berikut menguraikan beberapa contoh kueri yang harus Anda gunakan saat menguji implementasi:
Callback MediaSession | Frasa “Ok Google” yang akan digunakan | |
---|---|---|
onPlay() |
"Putar". “Lanjutkan.” |
|
onPlayFromSearch()
onPlayFromUri() |
Musik |
“Putar musik atau lagu di (nama aplikasi)”. Ini adalah kueri kosong. “Putar (lagu | artis | album | genre | playlist) di (nama aplikasi)”. |
Radio | “Putar (frequency | stasiun) di (nama aplikasi).” | |
Audiobook |
“Baca buku audio saya di (nama aplikasi)”. “Baca (buku audio) di (nama aplikasi)”. |
|
Podcast | “Putar (podcast) di (nama aplikasi).” | |
onPause() |
“Jeda.” | |
onStop() |
“Berhenti.” | |
onSkipToNext() |
“Berikutnya (lagu | episode | trek).” | |
onSkipToPrevious() |
“Sebelumnya (lagu | episode | trek).” | |
onSeekTo() |
"Mulai ulang." “Lewati maju ## detik.” “Kembali ke ## menit”. |
|
T/A (terus perbarui
MediaMetadata
Anda) |
“Apa yang sedang diputar?” |
Error
Asisten menangani error dari sesi media saat terjadi, dan melaporkannya
kepada pengguna. Pastikan sesi media Anda memperbarui status transpor dan
kode error dalam PlaybackState
-nya dengan benar, seperti dijelaskan dalam Menangani
sesi media. Asisten
mengenali semua kode error yang ditampilkan oleh
getErrorCode()
.
Kasus yang sering salah ditangani
Berikut adalah beberapa contoh kasus error yang harus dipastikan ditangani dengan benar:
- Pengguna harus login
- Setel kode error
PlaybackState
keERROR_CODE_AUTHENTICATION_EXPIRED
. - Setel pesan error
PlaybackState
. - Jika diperlukan untuk pemutaran, tetapkan status
PlaybackState
keSTATE_ERROR
. Jika tidak, pertahankan sisaPlaybackState
apa adanya.
- Setel kode error
- Pengguna meminta tindakan yang tidak tersedia
- Setel kode error
PlaybackState
dengan benar. Misalnya, tetapkanPlaybackState
keERROR_CODE_NOT_SUPPORTED
jika tindakan tidak didukung, atauERROR_CODE_PREMIUM_ACCOUNT_REQUIRED
jika tindakan tersebut dilindungi untuk login. - Setel pesan error
PlaybackState
. - Pertahankan sisa
PlaybackState
apa adanya.
- Setel kode error
- Pengguna meminta konten yang tidak tersedia dalam aplikasi
- Setel kode error
PlaybackState
dengan benar. Misalnya, gunakanERROR_CODE_NOT_AVAILABLE_IN_REGION
. - Setel pesan error
PlaybackState
. - Setel status
PlaybackSate
keSTATE_ERROR
untuk mengganggu pemutaran, jika tidak, pertahankanPlaybackState
sebagaimana adanya.
- Setel kode error
- Pengguna meminta konten yang pencocokan persisnya tidak tersedia. Misalnya, pengguna paket gratis yang meminta konten yang hanya tersedia untuk pengguna paket premium.
- Sebaiknya Anda tidak menampilkan error, dan sebaiknya prioritaskan menemukan sesuatu yang serupa untuk diputar. Asisten akan menangani pengucapan respons suara yang paling relevan sebelum pemutaran dimulai.
Memulai pemutaran dengan intent
Asisten dapat meluncurkan aplikasi audio atau video dan memulai pemutaran dengan mengirimkan intent menggunakan deep link.
Intent dan deep link-nya dapat berasal dari sumber berbeda:
- Saat memulai aplikasi seluler, Asisten dapat menggunakan Google Penelusuran untuk mengambil konten yang di-markup yang memberikan tindakan tonton dengan link.
- Saat Asisten memulai aplikasi TV, aplikasi Anda harus menyertakan
Penyedia Penelusuran TV
untuk mengekspos URI bagi konten media. Asisten mengirimkan kueri ke
penyedia konten yang akan menampilkan intent yang berisi URI untuk deep link dan
tindakan opsional.
Jika kueri menampilkan tindakan dalam intent,
Asisten akan mengirimkan tindakan tersebut dan URI kembali ke aplikasi Anda.
Jika penyedia tidak menentukan
tindakan, Asisten akan menambahkan
ACTION_VIEW
ke Intent.
Asisten menambahkan EXTRA_START_PLAYBACK
tambahan dengan nilai true
ke intent yang dikirimkannya ke aplikasi Anda. Aplikasi akan memulai pemutaran saat
menerima intent dengan EXTRA_START_PLAYBACK
.
Menangani intent selagi aktif
Pengguna dapat meminta Asisten untuk memutar sesuatu saat aplikasi Anda masih memutar konten dari permintaan sebelumnya. Artinya, aplikasi Anda dapat menerima intent baru untuk memulai pemutaran saat aktivitas pemutarannya sudah diluncurkan dan aktif.
Aktivitas yang mendukung intent dengan deep link harus mengganti
onNewIntent()
untuk menangani permintaan baru.
Saat memulai pemutaran, Asisten mungkin menambahkan tanda
tambahan
ke intent yang dikirimkan ke aplikasi Anda. Secara khusus, Asisten dapat menambahkan
FLAG_ACTIVITY_CLEAR_TOP
atau
FLAG_ACTIVITY_NEW_TASK
atau keduanya. Meskipun kode Anda
tidak perlu menangani flag ini, sistem Android akan meresponsnya.
Hal ini dapat memengaruhi perilaku aplikasi Anda saat permintaan pemutaran kedua dengan URI baru tiba
saat URI sebelumnya masih diputar. Dalam kasus semacam ini, ada baiknya untuk menguji respons aplikasi Anda. Anda dapat menggunakan alat command line adb
untuk menyimulasikan situasi ini (konstanta 0x14000000
adalah bitwise boolean OR dari dua tanda):
adb shell 'am start -a android.intent.action.VIEW --ez android.intent.extra.START_PLAYBACK true -d "<first_uri>"' -f 0x14000000
adb shell 'am start -a android.intent.action.VIEW --ez android.intent.extra.START_PLAYBACK true -d "<second_uri>"' -f 0x14000000
Pemutaran dari layanan
Jika aplikasi Anda memiliki
media browser service
yang mengizinkan koneksi dari Asisten,
Asisten dapat memulai aplikasi dengan berkomunikasi dengan
media session
layanan.
Layanan browser media tidak boleh meluncurkan Aktivitas.
Asisten akan meluncurkan Aktivitas Anda berdasarkan PendingIntent
yang Anda tentukan
dengan setSessionActivity().
Pastikan Anda menetapkan MediaSession.Token saat menginisialisasi layanan browser media. Jangan lupa menyetel tindakan pemutaran yang didukung setiap saat, termasuk selama inisialisasi. Asisten mengharapkan aplikasi media Anda menyetel tindakan pemutaran sebelum Asisten mengirimkan perintah pemutaran pertama.
Untuk memulai dari layanan, Asisten akan menerapkan API klien browser media. Aplikasi ini melakukan panggilan TransportControls yang memicu callback tindakan PLAY pada sesi media aplikasi Anda.
Diagram berikut menunjukkan urutan panggilan yang dihasilkan oleh Asisten dan callback sesi media yang sesuai. (Callback persiapan dikirim hanya jika aplikasi Anda mendukungnya.) Semua panggilan bersifat asinkron. Asisten tidak menunggu respons apa pun dari aplikasi Anda.
Saat pengguna mengeluarkan perintah suara untuk memutar media, Asisten merespons dengan pengumuman singkat. Segera setelah pengumuman itu selesai, Asisten akan mengeluarkan tindakan PLAY. Asisten tidak menunggu status pemutaran tertentu.
Jika aplikasi Anda mendukung tindakan ACTION_PREPARE_*
, Asisten akan memanggil tindakan PREPARE
sebelum memulai pengumuman.
Membuat koneksi ke MediaBrowserService
Agar dapat menggunakan layanan untuk memulai aplikasi, Asisten harus dapat terhubung ke MediaBrowserService aplikasi dan
mengambil MediaSession.Token-nya. Permintaan koneksi ditangani dalam metode onGetRoot()
layanan. Ada dua cara untuk menangani permintaan:
- Menerima semua permintaan koneksi
- Menerima permintaan koneksi dari aplikasi Asisten saja
Menerima semua permintaan koneksi
Anda harus menampilkan BrowserRoot agar dapat mengizinkan Asisten untuk mengirimkan perintah ke sesi media Anda. Cara termudahnya adalah dengan mengizinkan semua aplikasi MediaBrowser untuk tersambung ke MediaBrowserService Anda. Anda harus menampilkan BrowserRoot bukan null. Berikut adalah kode yang berlaku dari Universal Music Player:
Kotlin
override fun onGetRoot( clientPackageName: String, clientUid: Int, rootHints: Bundle? ): BrowserRoot? { // To ensure you are not allowing any arbitrary app to browse your app's contents, you // need to check the origin: if (!packageValidator.isCallerAllowed(this, clientPackageName, clientUid)) { // If the request comes from an untrusted package, return an empty browser root. // If you return null, then the media browser will not be able to connect and // no further calls will be made to other media browsing methods. Log.i(TAG, "OnGetRoot: Browsing NOT ALLOWED for unknown caller. Returning empty " + "browser root so all apps can use MediaController. $clientPackageName") return MediaBrowserServiceCompat.BrowserRoot(MEDIA_ID_EMPTY_ROOT, null) } // Return browser roots for browsing... }
Java
@Override public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid, Bundle rootHints) { // To ensure you are not allowing any arbitrary app to browse your app's contents, you // need to check the origin: if (!packageValidator.isCallerAllowed(this, clientPackageName, clientUid)) { // If the request comes from an untrusted package, return an empty browser root. // If you return null, then the media browser will not be able to connect and // no further calls will be made to other media browsing methods. LogHelper.i(TAG, "OnGetRoot: Browsing NOT ALLOWED for unknown caller. " + "Returning empty browser root so all apps can use MediaController." + clientPackageName); return new MediaBrowserServiceCompat.BrowserRoot(MEDIA_ID_EMPTY_ROOT, null); } // Return browser roots for browsing... }
Menerima paket dan tanda tangan aplikasi Asisten
Anda dapat secara eksplisit mengizinkan Asisten untuk tersambung ke layanan browser media dengan memeriksa nama dan tanda tangan paketnya. Aplikasi Anda akan menerima nama paket dalam metode onGetRoot MediaBrowserService. Anda harus menampilkan BrowserRoot agar dapat mengizinkan Asisten untuk mengirimkan perintah ke sesi media Anda. Contoh Universal Music Player memelihara daftar nama dan tanda tangan paket yang dikenal. Di bawah ini adalah nama dan tanda tangan paket yang digunakan oleh Asisten Google.
<signature name="Google" package="com.google.android.googlequicksearchbox">
<key release="false">19:75:b2:f1:71:77:bc:89:a5:df:f3:1f:9e:64:a6:ca:e2:81:a5:3d:c1:d1:d5:9b:1d:14:7f:e1:c8:2a:fa:00</key>
<key release="true">f0:fd:6c:5b:41:0f:25:cb:25:c3:b5:33:46:c8:97:2f:ae:30:f8:ee:74:11:df:91:04:80:ad:6b:2d:60:db:83</key>
</signature>
<signature name="Google Assistant on Android Automotive OS" package="com.google.android.carassistant">
<key release="false">17:E2:81:11:06:2F:97:A8:60:79:7A:83:70:5B:F8:2C:7C:C0:29:35:56:6D:46:22:BC:4E:CF:EE:1B:EB:F8:15</key>
<key release="true">74:B6:FB:F7:10:E8:D9:0D:44:D3:40:12:58:89:B4:23:06:A6:2C:43:79:D0:E5:A6:62:20:E3:A6:8A:BF:90:E2</key>
</signature>