Perangkat TV memerlukan perangkat keras sekunder untuk berinteraksi dengan aplikasi—perangkat keras pengontrol jarak jauh atau pengontrol game. Oleh karena itu, aplikasi Anda harus mendukung input tombol arah (D-pad). Selain itu, aplikasi Anda mungkin perlu menangani pengontrol yang offline dan input dari lebih dari satu jenis pengontrol.
Panduan ini membahas persyaratan dalam menangani pengontrol untuk perangkat TV.
Kontrol minimum D-pad
Pengontrol default untuk perangkat TV adalah D-pad. Secara umum, aplikasi harus dapat dioperasikan dari pengontrol jarak jauh yang hanya memiliki tombol atas, bawah, kiri, kanan, pilih, Kembali, dan Beranda. Jika aplikasi Anda adalah game yang biasanya membutuhkan pengontrol {i>game<i} dengan kontrol tambahan, mencoba mendukung gameplay hanya dengan kontrol D-pad ini. Jika tidak, peringatkan pengguna bahwa diperlukan pengontrol dan membiarkannya keluar dari game dengan baik menggunakan pengontrol D-pad.
Untuk informasi selengkapnya tentang navigasi dengan pengontrol D-pad untuk perangkat TV, lihat Navigasi TV.
Menangani pemutusan sambungan pengontrol
Pengontrol untuk TV seringkali merupakan perangkat Bluetooth, yang mungkin berupaya menghemat daya dengan secara berkala masuk ke mode tidur dan memutuskan diri dari perangkat TV. Ini berarti bahwa suatu aplikasi mungkin terganggu atau dimulai ulang jika tidak dikonfigurasi untuk menangani peristiwa penyambungan ulang ini. Acara ini dapat terjadi dalam salah satu situasi berikut:
- Sementara video yang berdurasi beberapa menit diputar, D-pad, atau game pengontrol mungkin masuk ke mode tidur, memutuskan sambungan dari perangkat TV, dan menyambungkan kembali nanti.
- Selama gameplay, pemain baru mungkin bergabung dalam game menggunakan pengontrol game yang belum terhubung.
- Selama gameplay, pemain dapat keluar dari game dan memutuskan sambungan pengontrol game.
Aktivitas aplikasi TV apa pun yang dapat menimbulkan peristiwa pemutusan koneksi dan penyambungan ulang harus dikonfigurasi untuk menangani peristiwa koneksi kembali dalam manifes aplikasi. Contoh kode berikut menunjukkan cara mengaktifkan aktivitas untuk menangani perubahan konfigurasi, termasuk keyboard atau perangkat navigasi menyambungkan, memutuskan sambungan, atau menyambungkan ulang:
<activity android:name="com.example.android.TvActivity" android:label="@string/app_name" android:configChanges="keyboard|keyboardHidden|navigation" android:theme="@style/Theme.Leanback"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LEANBACK_LAUNCHER" /> </intent-filter> ... </activity>
Perubahan konfigurasi ini memungkinkan aplikasi terus berjalan melalui koneksi ulang — bukannya dimulai ulang oleh framework Android, yang bukan pengalaman pengguna yang baik.
Menangani variasi input D-pad
Pengguna perangkat TV mungkin memiliki lebih dari satu jenis pengontrol yang digunakan dengan TV mereka. Sebagai contoh, pengguna mungkin memiliki pengontrol D-pad dasar dan pengontrol game. Kode tombol yang disediakan oleh pengontrol game saat digunakan untuk fungsi D-pad mungkin berbeda dari tombol kode yang dikirim oleh D-pad dasar.
Menangani variasi dalam input D-pad sehingga pengguna tidak harus beralih pengontrol untuk mengoperasikan aplikasi Anda. Untuk informasi selengkapnya tentang penanganan variasi input, lihat Memproses input tombol arah.
Menangani peristiwa tombol
Saat pengguna mengklik tombol pada pengontrol, aplikasi Anda akan menerima peristiwa dengan
KeyEvent
. Tujuan
untuk tombol mungkin berupa peristiwa media, seperti putar, jeda, atau berhenti, atau mungkin peristiwa jenis TV, seperti
pilihan atau navigasi. Untuk memberikan pengalaman pengguna yang baik, gunakan
perilaku tombol pengontrol.
Peristiwa UI TV
Tetapkan perilaku UI TV ke tombol yang menghasilkan KeyEvent
seperti yang ditunjukkan dalam tabel berikut:
KeyEvent | Perilaku |
---|---|
KEYCODE_BUTTON_B , KEYCODE_BACK | Kembali |
KEYCODE_BUTTON_SELECT , KEYCODE_BUTTON_A , KEYCODE_ENTER ,
KEYCODE_DPAD_CENTER , KEYCODE_NUMPAD_ENTER | Pemilihan |
KEYCODE_DPAD_UP , KEYCODE_DPAD_DOWN , KEYCODE_DPAD_LEFT ,
KEYCODE_DPAD_RIGHT | Navigasi |
Peristiwa media
Saat pengguna menonton media, tetapkan perilaku tombol yang menghasilkan
KeyEvent
seperti yang ditunjukkan dalam tabel berikut. Jika aplikasi Anda mengontrol
MediaSession
,
gunakan MediaControllerAdapter
untuk memanggil salah satu MediaControllerCompat.TransportControls
yang ditampilkan dalam tabel. Perhatikan bahwa tombol pilihan berfungsi sebagai Putar atau Jeda
tombol dalam konteks ini.
KeyEvent | Panggilan TransportControls | Perilaku |
---|---|---|
BUTTON_SELECT , BUTTON_A , ENTER ,
DPAD_CENTER , KEYCODE_NUMPAD_ENTER |
play() | Putar |
BUTTON_START , BUTTON_SELECT , BUTTON_A ,
ENTER , DPAD_CENTER , KEYCODE_NUMPAD_ENTER |
pause() | Jeda |
BUTTON_R1 | skipToNext() | Lewati ke berikutnya |
BUTTON_L1 | skipToPrevious() | Lewati ke sebelumnya |
DPAD_RIGHT , BUTTON_R2 , AXIS_RTRIGGER ,
AXIS_THROTTLE | fastForward() | Video dimajukan |
DPAD_LEFT , BUTTON_L2 , AXIS_LTRIGGER ,
AXIS_BRAKE | rewind() | Mundur |
T/A | stop() | Berhenti |
Catatan: Saat Anda menggunakan MediaSession
, jangan mengganti penanganan
tombol khusus media, seperti
KEYCODE_MEDIA_PLAY
atau KEYCODE_MEDIA_PAUSE
.
Sistem secara otomatis akan memicu
MediaSession.Callback
.
Memberikan perilaku tombol Kembali yang sesuai
Tombol Kembali tidak boleh berfungsi sebagai tombol. Misalnya, jangan menggunakannya untuk membuka dan menutup Google Spreadsheet. Hanya gunakan untuk menavigasi mundur, dengan gaya breadcrumb, melalui layar sebelumnya yang dilakukan pemain telah diaktifkan.
Karena tombol Kembali hanya melakukan navigasi linear dan mundur, Anda bisa menggunakan untuk membiarkan menu dalam aplikasi dibuka oleh tombol lain dan kembali ke aplikasi. Menekan tombol Kembali secara berurutan pada akhirnya harus selalu mengarah ke layar utama Android TV. Misalnya: gameplay > layar jeda game > layar utama game > Layar utama Android TV atau Penayangan acara TV > Layar utama aplikasi TV > Layar utama Android TV.
Untuk informasi selengkapnya tentang desain untuk navigasi, lihat Mendesain navigasi Kembali dan Atas. Untuk mempelajari implementasi, lihat Menyediakan navigasi kembali yang tepat.
Menangani pengontrol untuk game
Mendukung kontrol D-pad
Rencanakan skema kontrol Anda di seputar kontrol D-pad, karena set kontrol ini adalah default untuk perangkat Android TV. Pemain harus dapat menggunakan D-pad untuk semua aspek game—tidak hanya mengontrol gameplay inti, tetapi juga menavigasi menu dan iklan. Karena alasan ini, pastikan game Android TV Anda tidak merujuk ke antarmuka sentuh dengan bahasa seperti "Ketuk di sini untuk melanjutkan."
Cara Anda membentuk interaksi pemain dengan pengontrol dapat menjadi kunci untuk mencapai pengguna yang hebat pengalaman yang lancar bagi developer. Pertimbangkan praktik terbaik berikut:
- Sampaikan persyaratan pengontrol sejak awal: gunakan deskripsi Google Play Anda untuk menyampaikan kepada pemain semua harapan tentang {i>controller<i}. Jika suatu {i>game<i} lebih cocok untuk gamepad dengan joystick daripada gamepad yang hanya memiliki D-pad, jelaskan hal ini. Pemain yang menggunakan {i>controller<i} yang tidak cocok untuk sebuah {i>game<i} mungkin memiliki pengalaman yang buruk dan memberikan game Anda peringkat buruk.
- Gunakan pemetaan tombol yang konsisten: pemetaan tombol yang intuitif adalah kuncinya menciptakan pengalaman pengguna yang baik. Misalnya, patuhi bea cukai yang diterima dengan menggunakan tombol A untuk menyetujui dan tombol B untuk membatalkan. Anda juga dapat menawarkan fleksibilitas dalam bentuk kemampuan pemetaan ulang. Untuk informasi selengkapnya tentang pemetaan tombol, lihat Menangani tindakan pengontrol.
- Deteksi kemampuan pengontrol dan sesuaikan dengan semestinya: buat kueri pengontrol kemampuannya dalam mengoptimalkan kecocokan antara pengontrol dan game. Misalnya, Anda mungkin bermaksud membuat pemain mengarahkan objek dengan melambaikan {i>controller<i} ke udara, tetapi jika pengontrol pemutar tidak memiliki hardware akselerometer dan giroskop, melambaikan tangan tidak berfungsi. Membuat kueri pengontrol dan, jika deteksi gerakan tidak didukung, beralihlah ke skema kontrol alternatif yang tersedia. Untuk informasi lebih lanjut terkait kueri kemampuan pengontrol, lihat Dukungan pengontrol di seluruh versi Android.
Menggunakan tombol yang sesuai
Tidak semua pengontrol game menyediakan tombol Mulai, Telusuri, atau Menu. Pastikan UI tidak bergantung pada penggunaan tombol-tombol ini.
Menangani banyak pengontrol
Saat beberapa pemain bermain game, masing-masing dengan pengontrolnya sendiri, penting untuk
memetakan setiap pasangan
pemain-pengontrol. Untuk informasi tentang cara mengimplementasikan nomor pengontrol
identifikasi, lihat
getControllerNumber()
.
Menangani pemutusan sambungan pengontrol
Jika sambungan pengontrol terputus di tengah-tengah gameplay, jeda game dan tampilkan dialog yang meminta pemutar terputus untuk menyambungkan kembali pengontrolnya.
Selain itu, tawarkan tips pemecahan masalah dalam dialog. Misalnya, beri tahu pemutar ke "Periksa koneksi Bluetooth Anda." Untuk informasi selengkapnya tentang cara mengimplementasikan perangkat input dukungan, lihat Menangani pengontrol tindakan dan Ringkasan Bluetooth.
Menampilkan petunjuk pengontrol
Jika game Anda menyediakan petunjuk kontrol game visual, gunakan gambar pengontrol yang bebas dari branding dan hanya menyertakan tombol yang kompatibel dengan Android.
Untuk contoh gambar pengontrol yang kompatibel dengan Android, download Template Gamepad Android TV (ZIP). Pengontrol ini mencakup pengontrol putih dengan latar belakang hitam dan pengontrol hitam pada latar belakang putih latar belakang—ditunjukkan pada gambar 1—sebagai {i>file<i} PNG dan sebagai {i>file<i} Adobe® Illustrator®.
![](https://developer.android.com/static/images/games/game-controller-buttons_2x.png?authuser=1&hl=id)
Gambar 1. Contoh petunjuk pengontrol menggunakan Template Gamepad Android TV.