Mengelola pengontrol TV

Perangkat TV memerlukan perangkat hardware sekunder untuk berinteraksi dengan aplikasi, yaitu pengontrol jarak jauh atau pengontrol game dasar. 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 memerlukan pengontrol game dengan kontrol tambahan, upayakan untuk mendukung gameplay hanya dengan kontrol D-pad ini. Jika tidak, peringatkan pengguna bahwa pengontrol diperlukan dan biarkan mereka keluar dari game dengan baik menggunakan pengontrol D-pad.

Untuk informasi selengkapnya tentang menangani navigasi dengan pengontrol D-pad untuk perangkat TV, lihat Navigasi TV.

Menangani pemutusan sambungan pengontrol

Pengontrol untuk TV sering kali merupakan perangkat Bluetooth, yang mungkin mencoba menghemat daya dengan secara berkala masuk ke mode tidur dan memutuskan koneksi dari perangkat TV. Ini berarti bahwa aplikasi mungkin akan terganggu atau dimulai ulang jika tidak dikonfigurasi untuk menangani peristiwa penyambungan kembali ini. Peristiwa ini dapat terjadi dalam salah satu situasi berikut:

  • Saat video berdurasi beberapa menit diputar, D-pad atau pengontrol game mungkin akan masuk ke mode tidur, memutuskan sambungan dari perangkat TV, dan menyambungkan kembali nanti.
  • Selama gameplay, pemain baru dapat bergabung ke game menggunakan pengontrol game yang belum terhubung.
  • Selama gameplay, pemain mungkin keluar dari game dan memutuskan sambungan pengontrol game.

Setiap aktivitas aplikasi TV yang dapat mengalami peristiwa pemutusan koneksi dan penyambungan kembali harus dikonfigurasi untuk menangani peristiwa penyambungan kembali dalam manifes aplikasi. Contoh kode berikut menunjukkan cara mengaktifkan aktivitas agar menangani perubahan konfigurasi, termasuk keyboard atau perangkat navigasi yang menyambungkan, memutuskan sambungan, atau menyambungkan kembali:

<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 peristiwa penyambungan kembali—bukan 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. Misalnya, pengguna mungkin memiliki pengontrol D-pad dasar dan pengontrol game. Kode tombol yang diberikan oleh pengontrol game saat digunakan untuk fungsi D-pad dapat berbeda dengan kode tombol yang dikirim oleh D-pad dasar.

Menangani variasi dalam input D-pad sehingga pengguna tidak perlu 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. Perilaku yang dimaksud untuk tombol mungkin berupa peristiwa media, seperti putar, jeda, atau hentikan, atau mungkin berupa peristiwa jenis TV, seperti pilihan atau navigasi. Untuk memberikan pengalaman pengguna yang baik, tetapkan perilaku yang konsisten pada tombol pengontrol.

Peristiwa UI TV

Tetapkan perilaku UI TV ke tombol yang menghasilkan jenis KeyEvent seperti yang ditunjukkan dalam tabel berikut:

KeyEventPerilaku
KEYCODE_BUTTON_B, KEYCODE_BACKKembali
KEYCODE_BUTTON_SELECT, KEYCODE_BUTTON_A, KEYCODE_ENTER, KEYCODE_DPAD_CENTER, KEYCODE_NUMPAD_ENTERPilihan
KEYCODE_DPAD_UP, KEYCODE_DPAD_DOWN, KEYCODE_DPAD_LEFT, KEYCODE_DPAD_RIGHTNavigasi

Peristiwa media

Saat pengguna menonton media, tetapkan perilaku ke tombol yang menghasilkan jenis KeyEvent seperti ditunjukkan dalam tabel berikut. Jika aplikasi Anda mengontrol MediaSession, gunakan MediaControllerAdapter untuk memanggil salah satu dari metode MediaControllerCompat.TransportControls yang ditampilkan dalam tabel. Perhatikan, tombol pemilihan berfungsi sebagai tombol Putar atau Jeda dalam konteks ini.

KeyEventPanggilan TransportControlsPerilaku
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_R1skipToNext()Lewati ke berikutnya
BUTTON_L1skipToPrevious()Lewati ke sebelumnya
DPAD_RIGHT, BUTTON_R2, AXIS_RTRIGGER, AXIS_THROTTLEfastForward()Maju cepat
DPAD_LEFT, BUTTON_L2, AXIS_LTRIGGER, AXIS_BRAKErewind()Mundur
T/Astop()Hentikan

Catatan: Saat Anda menggunakan MediaSession, jangan mengganti penanganan tombol khusus media, seperti KEYCODE_MEDIA_PLAY atau KEYCODE_MEDIA_PAUSE. Sistem akan otomatis memicu metode MediaSession.Callback yang sesuai.

Menyediakan perilaku tombol Kembali yang sesuai

Tombol Kembali tidak boleh berfungsi sebagai tombol beralih. Misalnya, jangan menggunakannya untuk membuka dan menutup menu. Gunakan hanya untuk menavigasi mundur dengan gaya breadcrumb, ke layar sebelumnya yang dikunjungi pemain.

Karena tombol Kembali hanya menjalankan navigasi mundur linear, Anda dapat menggunakannya untuk membiarkan menu dalam aplikasi terbuka oleh tombol lain dan kembali ke aplikasi. Menekan tombol Kembali secara berturut-turut pada akhirnya harus selalu mengarah ke layar utama Android TV. Misalnya: gameplay > layar jeda game > layar utama game > layar utama Android TV atau pemutaran 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 kumpulan kontrol ini merupakan 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 pengalaman pengguna yang luar biasa. Pertimbangkan praktik terbaik berikut:

  • Sampaikan persyaratan pengontrol di awal: gunakan deskripsi Google Play Anda untuk menyampaikan kepada pemain ekspektasi apa pun tentang pengontrol. Jika game lebih cocok untuk gamepad yang menggunakan joystick daripada D-pad, jelaskan hal tersebut. Pemain yang menggunakan pengontrol yang tidak sesuai untuk sebuah game mungkin akan mendapatkan pengalaman yang buruk dan memberikan rating buruk pada game Anda.
  • Gunakan pemetaan tombol yang konsisten: pemetaan tombol yang intuitif adalah kunci untuk pengalaman pengguna yang baik. Misalnya, patuhi ketentuan bea cukai yang diterima menggunakan tombol A untuk menerima dan tombol B untuk membatalkan. Anda juga dapat menawarkan fleksibilitas dalam bentuk kemampuan pemetaan ulang. Untuk mengetahui informasi selengkapnya tentang pemetaan tombol, baca Menangani tindakan pengontrol.
  • Deteksi kemampuan pengontrol dan sesuaikan: buat kueri pengontrol tentang kemampuannya untuk mengoptimalkan kecocokan antara pengontrol dan game. Misalnya, Anda mungkin bermaksud agar pemain mengarahkan objek dengan melambaikan pengontrol di udara, tetapi jika pengontrol pemain tidak memiliki hardware akselerometer dan giroskop, melambaikan tangan tidak akan berfungsi. Buat kueri terhadap pengontrol dan, jika deteksi gerakan tidak didukung, beralihlah ke skema kontrol alternatif yang tersedia. Untuk mengetahui informasi selengkapnya tentang mengkueri kemampuan pengontrol, lihat Mendukung pengontrol di berbagai versi Android.

Menggunakan tombol yang sesuai

Tidak semua pengontrol game menyediakan tombol Mulai, Telusuri, atau Menu. Pastikan UI Anda tidak bergantung pada penggunaan tombol-tombol tersebut.

Menangani banyak pengontrol

Saat beberapa pemain memainkan sebuah game, masing-masing menggunakan pengontrolnya sendiri, sebaiknya petakan setiap pasangan pemain-pengontrol. Untuk informasi cara mengimplementasikan identifikasi nomor pengontrol, lihat getControllerNumber().

Menangani pemutusan sambungan pengontrol

Saat sambungan pengontrol terputus di tengah-tengah gameplay, jeda game dan tampilkan dialog yang meminta pemain yang terputus tersebut untuk menghubungkan kembali pengontrolnya.

Selain itu, tawarkan tips pemecahan masalah dalam dialog tersebut. Misalnya, beri tahu pemutar untuk "Periksa koneksi Bluetooth Anda". Untuk informasi selengkapnya tentang mengimplementasikan dukungan perangkat input, lihat Menangani tindakan pengontrol dan Ringkasan Bluetooth.

Menampilkan petunjuk pengontrol

Jika game Anda menyediakan petunjuk kontrol game visual, gunakan gambar pengontrol tanpa branding dan hanya sertakan tombol yang kompatibel dengan Android.

Untuk contoh gambar pengontrol yang kompatibel dengan Android, download Template Gamepad Android TV (ZIP). Tampilan ini mencakup pengontrol putih pada latar belakang hitam dan pengontrol hitam pada latar belakang putih—yang ditunjukkan pada gambar 1—sebagai file PNG dan sebagai file Adobe® Illustrator®.

Gambar 1. Contoh petunjuk pengontrol menggunakan Template Gamepad Android TV.