Mengelola pengontrol TV

Perangkat TV memerlukan perangkat hardware sekunder untuk berinteraksi dengan aplikasi—remote control dasar, remote pointer, atau pengontrol game. Untuk memberikan pengalaman pengguna yang konsisten, aplikasi Anda harus mendukung input tombol arah (D-pad), menangani pengontrol yang offline, dan mendukung input dari beberapa jenis pengontrol, termasuk remote pointer.

Kontrol minimum D-pad

Pengontrol default untuk perangkat TV adalah D-pad. Secara umum, aplikasi Anda harus dapat dioperasikan dari remote control yang hanya memiliki tombol atas, bawah, kiri, kanan, pilih, Kembali, dan Layar Utama. Jika aplikasi Anda adalah game yang biasanya memerlukan pengontrol game dengan kontrol tambahan, coba dukung gameplay hanya dengan kontrol D-pad ini. Jika tidak, beri tahu pengguna bahwa pengontrol diperlukan dan biarkan mereka 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 sering kali merupakan perangkat Bluetooth, yang mungkin mencoba menghemat daya dengan secara berkala beralih ke mode tidur dan memutuskan koneksi dari perangkat TV. Artinya, aplikasi mungkin terganggu atau dimulai ulang jika tidak dikonfigurasi untuk menangani peristiwa koneksi ulang ini. Peristiwa ini dapat terjadi dalam salah satu keadaan berikut:

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

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

<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 koneksi ulang—bukan dimulai ulang oleh framework Android, yang bukan merupakan 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, remote penunjuk, atau pengontrol game. Kode tombol yang disediakan oleh pengontrol game saat digunakan untuk fungsi D-pad mungkin berbeda dengan kode tombol yang dikirim oleh D-pad dasar.

Tangani variasi dalam input D-pad sehingga pengguna tidak perlu beralih pengontrol untuk mengoperasikan aplikasi Anda. Untuk informasi selengkapnya tentang menangani variasi input, lihat Memproses input tombol arah.

Mendukung remote pointer

Beberapa perangkat TV mendukung remote pointer, seperti air mouse atau remote dengan pad arah yang sensitif terhadap sentuhan (trackpad). Mendukung remote pointer memungkinkan pengguna berinteraksi dengan aplikasi Anda menggunakan gestur tunjuk dan klik, arahkan kursor, geser, dan tarik, sehingga memberikan pengalaman yang lebih lancar pada hardware yang kompatibel sekaligus mempertahankan kompatibilitas D-pad penuh.

Mendeklarasikan dukungan remote pointer dalam manifes

Untuk menunjukkan bahwa aplikasi Anda dapat dinavigasi dengan input pointer dan sentuh, konfigurasikan manifes aplikasi Anda dengan android.software.leanback.supports_touch <property> yang ditetapkan ke true di dalam elemen <application> (atau di dalam elemen <activity> individual untuk mengonfigurasi dukungan per aktivitas):

<manifest ...>
    <!-- Signal whether the app is adaptive or built just for TV -->
    <uses-feature
        android:name="android.software.leanback"
        android:required="true|false" />
    <!-- Ensure the app can be installed on conventional TVs -->
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <application ...>
        <!-- Signal whether the app supports pointer remotes -->
        <property
            android:name="android.software.leanback.supports_touch"
            android:value="true" />
        ...
    </application>
</manifest>

Mendukung interaksi klik, pengarahan kursor, dan scroll

Saat mendukung remote pointer, pastikan komponen UI Anda merespons input kursor dan sentuh dengan tepat di seluruh interaksi berikut:

• Klik dan pemilihan: semua elemen UI yang dapat difokuskan dan dipilih harus dapat diklik dengan remote pointer, yang cocok dengan perilaku pemilihan D-pad (KEYCODE_DPAD_CENTER).
  • Jetpack Compose: gunakan pengubah Modifier.clickable() atau pointerInput. Untuk mengetahui detail selengkapnya, lihat Ketuk dan tekan.
  • Tampilan: menangani peristiwa klik pada tampilan. Untuk mengetahui detail selengkapnya, lihat Ringkasan peristiwa input.
• Status pengarahan kursor visual: memberikan efek pengarahan kursor visual yang jelas untuk menunjukkan saat kursor pointer diposisikan di atas item yang dapat dipilih.
  • Jetpack Compose: gunakan Modifier.hoverable() atau amati status pengarahan kursor menggunakan InteractionSource. Untuk mengetahui detail selengkapnya, lihat Menangani interaksi pengguna.
  • View: tentukan status pengarahan kursor menggunakan drawable daftar status dengan android:state_hovered="true".
• Scroll geser dan jentik: scroll horizontal dan vertikal yang dipicu oleh gestur geser atau jentik pada tombol D-pad tengah yang sensitif terhadap sentuhan harus berfungsi dengan lancar di semua konten yang dapat di-scroll.
• Scroll tarik: pengguna harus dapat menarik untuk men-scroll secara vertikal (ke atas dan ke bawah) atau horizontal (ke kiri dan ke kanan) di seluruh penampung yang dapat di-scroll.
  • Jetpack Compose: penampung standar yang dapat di-scroll secara default mendukung scroll pointer dan sentuh. Untuk implementasi kustom, lihat Input pointer di Compose.
  • Tampilan: tampilan standar yang dapat di-scroll mendukung scroll sentuh secara default. Untuk penanganan input kustom, lihat Sentuhan dan input.
• Penggeseran pemutaran media: selama pemutaran media (seperti acara TV dan film), pengguna harus dapat berinteraksi dengan status progres pemutaran (bilah geser) dengan mengarahkan kursor dan mengklik untuk melompat ke stempel waktu sebelumnya atau berikutnya, serta menarik (menggeser) di sepanjang status progres untuk mencari waktu tertentu.

Menangani peristiwa tombol

Saat pengguna mengklik tombol pada pengontrol, aplikasi Anda akan menerima peristiwa dengan KeyEvent. Perilaku yang diinginkan untuk tombol mungkin berupa peristiwa media, seperti putar, jeda, atau berhenti, atau mungkin peristiwa jenis TV, seperti pemilihan atau navigasi. Untuk memberikan pengalaman pengguna yang baik, tetapkan perilaku yang konsisten ke tombol pengontrol.

Peristiwa UI TV

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

Peristiwa media

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

Memberikan perilaku tombol Kembali yang sesuai

Tombol Kembali tidak boleh berfungsi sebagai tombol akses. Misalnya, jangan gunakan untuk membuka dan menutup menu. Hanya gunakan tombol ini untuk menavigasi mundur, dengan gaya breadcrumb, melalui layar sebelumnya yang telah dibuka pemain.

Karena tombol Kembali hanya melakukan navigasi linear ke belakang, Anda dapat menggunakannya untuk keluar dari menu dalam aplikasi yang dibuka oleh tombol lain dan kembali ke aplikasi. Menekan tombol Kembali secara berturut-turut 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 penerapan, lihat Menyediakan navigasi kembali yang tepat.

Menangani pengontrol untuk game

Saat membuat game untuk Android TV, desain skema kontrol Anda agar berfungsi dengan remote TV standar dan controller game khusus.

Mendukung kontrol D-pad

Rencanakan skema kontrol Anda di sekitar 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. Oleh karena itu, 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 untuk menyampaikan ekspektasi apa pun tentang pengontrol kepada pemain. Jika game lebih cocok untuk gamepad dengan joystick daripada gamepad yang hanya memiliki D-pad, jelaskan hal ini. Pemain yang menggunakan pengontrol yang tidak sesuai untuk game mungkin akan mendapatkan pengalaman yang buruk dan memberikan rating yang buruk untuk game Anda.
• Gunakan pemetaan tombol yang konsisten: pemetaan tombol yang intuitif adalah kunci untuk pengalaman pengguna yang baik. Misalnya, patuhi kebiasaan yang diterima dengan menggunakan tombol A untuk menerima dan tombol B untuk membatalkan. Anda juga dapat menawarkan fleksibilitas dengan mengizinkan pengguna memetakan ulang tombol. Untuk mengetahui informasi selengkapnya tentang pemetaan tombol, lihat Menangani tindakan pengontrol.
• Mendeteksi kemampuan pengontrol dan menyesuaikannya: buat kueri pengontrol tentang kemampuannya untuk mengoptimalkan kecocokan antara pengontrol dan game. Misalnya, Anda mungkin ingin pemain mengarahkan objek dengan mengayunkan pengontrol di udara, tetapi jika pengontrol pemain tidak memiliki hardware akselerometer dan giroskop, mengayunkan pengontrol tidak akan berfungsi. Buat kueri pengontrol dan, jika deteksi gerakan tidak didukung, beralihlah ke skema kontrol alternatif yang tersedia. Untuk mengetahui informasi selengkapnya tentang cara mengkueri kemampuan pengontrol, lihat Mendukung pengontrol di seluruh versi Android.

Menggunakan tombol yang sesuai

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

Menangani banyak pengontrol

Saat beberapa pemain memainkan game, masing-masing dengan pengontrolnya sendiri, penting untuk memetakan setiap pasangan pemain-pengontrol. Untuk mengetahui informasi tentang cara menerapkan identifikasi nomor pengontrol, lihat getControllerNumber().

Menangani pemutusan sambungan pengontrol

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

Selain itu, tawarkan tips pemecahan masalah dalam dialog. Misalnya, beri tahu pemain untuk "Memeriksa koneksi Bluetooth". Untuk mengetahui informasi selengkapnya tentang cara menerapkan 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). Logo ini mencakup pengontrol putih dengan latar belakang hitam dan pengontrol hitam dengan latar belakang putih—ditampilkan dalam gambar 1—sebagai file PNG dan sebagai file Adobe® Illustrator®.