Mengelola pengontrol TV

Perangkat TV memerlukan perangkat hardware sekunder untuk berinteraksi dengan aplikasi—pengontrol jarak jauh 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 penunjuk.

Kontrol minimum D-pad

Pengontrol default untuk perangkat TV adalah D-pad. Secara umum, aplikasi Anda harus dapat dioperasikan dari pengontrol jarak jauh 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, peringatkan pengguna bahwa pengontrol diperlukan dan izinkan mereka keluar dari game Anda dengan baik menggunakan pengontrol D-pad.

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

Menangani pemutusan sambungan pengontrol

Pengontrol untuk TV sering kali berupa perangkat Bluetooth, yang mungkin mencoba menghemat daya dengan secara berkala masuk ke mode tidur dan berhenti terhubung dari perangkat TV. Artinya, aplikasi mungkin terganggu atau dimulai ulang jika tidak dikonfigurasi untuk menangani peristiwa penghubungan kembali ini. Peristiwa ini dapat terjadi dalam salah satu situasi berikut:

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

Aktivitas aplikasi TV apa pun yang tunduk pada peristiwa koneksi terputus dan terhubung kembali harus dikonfigurasi untuk menangani peristiwa koneksi ulang dalam manifes aplikasi. Contoh kode berikut menunjukkan cara mengaktifkan aktivitas untuk menangani perubahan konfigurasi, termasuk saat keyboard atau perangkat navigasi terhubung, terputus, atau terhubung 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 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 mereka gunakan dengan TV. 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 dapat bervariasi dari kode tombol yang dikirim oleh D-pad dasar.

Tangani variasi input D-pad sehingga pengguna tidak perlu mengganti pengontrol untuk mengoperasikan aplikasi Anda. Untuk mengetahui informasi selengkapnya tentang cara menangani variasi input, lihat Memproses input pad terarah.

Mendukung remote pointer

Beberapa perangkat TV mendukung remote pointer, seperti mouse udara atau remote dengan pad arah sentuh (trackpad). Dengan mendukung remote penunjuk, pengguna dapat berinteraksi dengan aplikasi Anda menggunakan gestur tunjuk dan klik, arahkan kursor, geser, dan tarik, sehingga memberikan pengalaman yang lebih lancar di hardware yang kompatibel sekaligus mempertahankan kompatibilitas D-pad penuh.

Mendeklarasikan dukungan remote pointer dalam manifes

Untuk menunjukkan bahwa aplikasi Anda dapat dinavigasi dengan input sentuh dan pointer, konfigurasikan manifes aplikasi Anda dengan metadata android.software.leanback.supports_touch yang ditetapkan ke true:

<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" />
    <!-- Signal whether the app supports pointer remotes -->
    <meta-data
        android:name="android.software.leanback.supports_touch"
        android:value="true" />
    <application ...>
        ...
    </application>
</manifest>

Mendukung interaksi klik, arahkan kursor, dan scroll

Saat mendukung remote pointer, pastikan komponen UI Anda merespons dengan tepat input sentuh dan kursor 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 kapan kursor penunjuk 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.
  • Tampilan: menentukan status mengarahkan kursor menggunakan drawable daftar status dengan android:state_hovered="true".
• Menggeser dan menggerakkan scroll: scroll horizontal dan vertikal yang dipicu oleh gestur menggeser atau menggerakkan pada tombol D-pad tengah yang sensitif terhadap sentuhan harus berfungsi lancar di semua konten yang dapat di-scroll.
• Men-scroll dengan menarik: pengguna harus dapat menarik untuk men-scroll secara vertikal (atas dan bawah) atau horizontal (kiri dan kanan) di seluruh penampung yang dapat di-scroll.
  • Jetpack Compose: penampung yang dapat di-scroll standar mendukung scroll pointer dan sentuh secara default. Untuk implementasi kustom, lihat Input pointer di Compose.
  • Tampilan: tampilan standar yang dapat di-scroll mendukung scrolling 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 (status bar) dengan mengarahkan dan mengklik untuk melompat ke stempel waktu sebelumnya atau mendatang, serta menarik (menggeser) status progres untuk mencari waktu tertentu.

Menangani peristiwa tombol

Saat pengguna mengklik tombol pada pengontrol, aplikasi Anda akan menerima peristiwa dengan KeyEvent. Perilaku yang dimaksudkan untuk tombol mungkin berupa peristiwa media, seperti putar, jeda, atau hentikan, atau mungkin berupa peristiwa jenis TV, seperti pemilihan 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:

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.

Menyediakan perilaku tombol Kembali yang sesuai

Tombol Kembali tidak boleh berfungsi sebagai tombol pengalih. Misalnya, jangan gunakan untuk membuka dan menutup menu. Gunakan hanya untuk menavigasi mundur, gaya breadcrumb, melalui layar sebelumnya yang telah dibuka oleh pemutar.

Karena tombol Kembali hanya melakukan navigasi mundur yang linear, 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 mengetahui informasi selengkapnya tentang desain untuk navigasi, lihat Mendesain navigasi Kembali dan Naik. Untuk mempelajari penerapan, lihat Menyediakan navigasi kembali yang tepat.

Menangani pengontrol untuk game

Saat membangun game untuk Android TV, desain skema kontrol Anda agar berfungsi dengan remote TV standar dan pengontrol 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 Anda untuk menyampaikan ekspektasi apa pun tentang pengontrol kepada pemain. Jika game lebih cocok untuk gamepad dengan joystick daripada game dengan hanya tombol D-pad, jelaskan hal ini. Pemain yang menggunakan pengontrol yang tidak sesuai untuk 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 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: 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 giroskop dan akselerometer, pengayunan tidak akan berfungsi. Kueri pengontrol dan, jika deteksi gerakan tidak didukung, beralih ke skema kontrol alternatif yang tersedia. Untuk mengetahui informasi selengkapnya tentang membuat kueri 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

Jika controller terputus di tengah permainan, jeda game dan tampilkan dialog yang meminta pemain yang terputus untuk menghubungkan kembali controllernya.

Selain itu, berikan tips pemecahan masalah dalam dialog. Misalnya, beri tahu pemain untuk "Periksa koneksi Bluetooth Anda". Untuk mengetahui informasi selengkapnya tentang penerapan dukungan perangkat input, lihat Menangani tindakan pengontrol dan Ringkasan Bluetooth.

Menampilkan petunjuk pengontrol

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

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