Membuat dan menjalankan aplikasi TV

Aplikasi TV menggunakan struktur yang sama dengan aplikasi untuk ponsel dan tablet. Persamaan ini berarti Anda bisa memodifikasi aplikasi yang ada agar juga berjalan di perangkat TV atau membuat aplikasi baru berdasarkan aplikasi yang sudah ketahui tentang membuat aplikasi untuk Android.

Penting: Aplikasi Anda harus memenuhi persyaratan khusus untuk memenuhi syarat sebagai aplikasi Android TV di Google Play. Untuk informasi selengkapnya, lihat persyaratan yang tercantum dalam kualitas aplikasi TV.

Panduan ini menjelaskan cara menyiapkan lingkungan pengembangan Anda untuk membuat aplikasi TV dan perubahan minimum yang diperlukan agar aplikasi dapat berjalan di perangkat TV.

Untuk informasi tentang cara mendesain aplikasi untuk TV, lihat Mendesain untuk TV. Lihat juga aplikasi contoh di Repositori GitHub Android TV.

Menentukan dukungan format media

Lihat dokumentasi berikut untuk informasi tentang codec, protokol, dan format didukung oleh Android TV:

Menyiapkan project TV

Bagian ini membahas cara menyiapkan proyek TV, baik Anda memodifikasi aplikasi Android yang ada untuk berjalan di perangkat TV atau membuat aplikasi TV baru. Jika sudah memiliki aplikasi Android, menambahkan dukungan Android TV memungkinkan Anda mendesain antarmuka pengguna untuk TV sambil menggunakan kembali arsitektur aplikasi Anda yang ada.

Ada dua komponen utama yang Anda gunakan saat membuat aplikasi yang berjalan di perangkat TV:

  • Aktivitas untuk TV: Dalam manifes aplikasi Anda, mendeklarasikan aktivitas yang dimaksudkan untuk berjalan di perangkat TV.
  • Koleksi TV: Opsional, sertakan satu atau beberapa Library androidx untuk perangkat TV, yang tercantum di bagian lain panduan ini. Library ini menyediakan widget untuk mem-build antarmuka pengguna.

Prasyarat

Sebelum mulai membuat aplikasi untuk TV, Anda harus melakukan langkah-langkah berikut:

  • Update SDK Tools ke versi 24.0.0 atau yang lebih tinggi.
    SDK Tools yang diupdate memungkinkan Anda membuat dan menguji aplikasi untuk TV.
  • Update SDK Anda dengan Android 5.0 (API 21) atau yang lebih tinggi.
    Versi platform yang diupdate menyediakan API baru untuk aplikasi TV.
  • Buat atau update project aplikasi Anda.
    Guna mengakses API baru untuk perangkat TV, buat project atau ubah project project yang menargetkan Android 5.0 (API level 21) atau yang lebih tinggi.

Mendeklarasikan aktivitas TV

Aplikasi yang dimaksudkan untuk berjalan di perangkat TV harus mendeklarasikan aktivitas peluncur untuk TV dalam manifesnya. Menggunakan intent CATEGORY_LEANBACK_LAUNCHER untuk melakukan ini. Filter ini mengidentifikasi bahwa aplikasi Anda diaktifkan untuk TV dan memungkinkan Google Play mengidentifikasinya sebagai aplikasi TV. Saat pengguna memilih aplikasi Anda di layar utama TV mereka, intent ini mengidentifikasi aktivitas mana yang akan diluncurkan.

Cuplikan kode berikut menunjukkan cara menyertakan filter intent ini dalam manifes:

<application
  android:banner="@drawable/banner" >
  ...
  <activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
  </activity>

  <activity
    android:name="com.example.android.TvActivity"
    android:label="@string/app_name"
    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>
</application>

Entri manifes aktivitas kedua dalam contoh ini menetapkan bahwa itu adalah aktivitas yang diluncurkan di perangkat TV.

Perhatian: Jika Anda tidak menyertakan filter intent CATEGORY_LEANBACK_LAUNCHER di aplikasi Anda, aplikasi tidak terlihat oleh pengguna yang menjalankan Google Play di perangkat TV. Selain itu, jika aplikasi tidak memiliki filter ini saat menggunakan alat developer untuk memuatnya ke perangkat TV, aplikasi tidak muncul dalam antarmuka pengguna TV.

Antarmuka pengguna aplikasi TV, atau bagian TV dari aplikasi yang ada, harus menyediakan antarmuka yang sederhana untuk navigasi yang mudah menggunakan remote control dari jarak 3 meter. Jika Anda memodifikasi aplikasi yang ada untuk digunakan di TV, jangan gunakan untuk TV yang Anda gunakan untuk ponsel dan tablet. Untuk panduan mendesain aplikasi TV, lihat Mendesain aplikasi untuk TV.

Mendeklarasikan dukungan perangkat TV

Deklarasikan bahwa aplikasi Anda dibuat untuk Android TV dengan mendeklarasikan android.software.leanback.

Jika aplikasi Anda berjalan di perangkat seluler dan TV, setel nilai atribut required ke false. Jika Anda menetapkan nilai atribut required ke true, Google Play hanya akan menyediakan aplikasi Anda di Android TV OS.

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

Tidak perlu mendeklarasikan layar sentuh

Aplikasi yang dimaksudkan untuk berjalan di perangkat TV tidak bergantung pada layar sentuh untuk input. Untuk memperjelas, manifes aplikasi TV Anda harus mendeklarasikan bahwa Fitur android.hardware.touchscreen tidak diperlukan. Setelan ini mengidentifikasi bahwa aplikasi Anda dapat berfungsi di perangkat TV, dan agar aplikasi Anda dianggap sebagai aplikasi TV di Google Google Play. Contoh kode berikut menunjukkan cara menyertakan deklarasi manifes ini:

<manifest>
    <uses-feature android:name="android.hardware.touchscreen"
              android:required="false" />
    ...
</manifest>

Perhatian: Dalam manifes aplikasi, Anda harus mendeklarasikan bahwa layar sentuh tidak diperlukan, seperti yang ditunjukkan pada kode contoh ini. Jika tidak, aplikasi Anda tidak akan muncul di Google Play di TV perangkat.

Menyediakan ikon dan banner layar utama

Aplikasi Android TV harus menyediakan ikon layar utama dan gambar banner untuk setiap pelokalan. Bergantung pada perangkat Android TV, ikon atau banner digunakan sebagai peluncuran aplikasi titik yang muncul di layar beranda dalam baris aplikasi dan game.

Untuk menambahkannya ke aplikasi Anda, deskripsikan ikon dan banner dalam manifes sebagai berikut:

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

Ikon layar utama

Aplikasi Android TV, seperti semua aplikasi Android, harus menyediakan ikon layar utama. Untuk praktik terbaik tentang menentukan titik peluncuran yang tepat untuk aplikasi Anda dan persyaratan aset terperinci, lihat Ikon dan banner aplikasi Android TV pedoman kami.

Menggunakan android:banner dengan <application> untuk menyediakan banner default bagi semua aktivitas aplikasi, atau dengan <activity> tag untuk menyediakan banner bagi aktivitas tertentu.

Untuk banner, gunakan resource xhdpi dengan ukuran 320 x 180 px. Teks harus disertakan dalam gambar. Jika aplikasi Anda tersedia dalam lebih dari satu bahasa, Anda harus memberikan versi terpisah dari banner dengan teks untuk setiap bahasa yang didukung.

Mengubah warna peluncur

Perhatian: Di Android 12 dan yang lebih baru, animasi layar pembuka kustom yang dibuat menggunakan API platform SplashScreen tidak didukung untuk aplikasi Android TV.

Saat aplikasi TV diluncurkan, sistem akan menampilkan animasi yang tampak seperti animasi yang diperluas lingkaran. Untuk menyesuaikan warna animasi ini, setel android:colorPrimary aplikasi TV atau aktivitas Anda ke warna tertentu. Selain itu, tetapkan dua transisi atribut tumpang-tindih ke true seperti yang ditunjukkan dalam cuplikan berikut dari file XML resource tema:

<resources>
    <style ... >
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>

Untuk informasi selengkapnya tentang cara menggunakan tema dan gaya, lihat Gaya dan Tema.

Membangun aplikasi untuk Android TV OS

Jetpack menyertakan library paket androidx untuk digunakan dengan aplikasi TV.

Compose untuk TV

Compose adalah cara yang direkomendasikan untuk membangun aplikasi untuk Android TV OS. Bersamaan dengan Compose inti library Compose untuk TV menyediakan komponen khusus yang dirancang khusus untuk layar TV:

Temukan cara membuat aplikasi TV menggunakan Compose untuk TV di artikel Menggunakan Jetpack Compose di Android TV.

Toolkit UI Leanback

Toolkit UI Leanback menyediakan API dan widget antarmuka pengguna untuk perangkat TV:

Temukan cara membangun aplikasi TV menggunakan toolkit UI Leanback di Membuat aplikasi pemutaran TV.

Menjalankan aplikasi TV

Menjalankan aplikasi merupakan bagian penting dari proses pengembangan. Anda dapat menjalankan aplikasi di Perangkat TV yang dikonfigurasi untuk mendukung proses debug USB atau menggunakan perangkat TV virtual.

Menjalankan aplikasi di perangkat fisik

Persiapkan perangkat TV Anda sebagai berikut:

  1. Gunakan kabel USB untuk menghubungkan perangkat TV ke mesin pengembangan. Jika diperlukan, lihat dokumentasi yang disediakan oleh produsen perangkat Anda.
  2. Di perangkat TV, navigasikan ke Settings.
  3. Di baris Device, pilih About.
  4. Scroll ke Build, lalu pilih Build beberapa kali sampai Anda mendapatkan pesan "Sekarang Anda adalah developer!"
  5. Kembali ke Settings. Di baris Preferences, pilih Developer options.
  6. Pilih Debugging > USB debugging lalu pilih On.
  7. Kembali ke layar utama TV.

Untuk menguji aplikasi di perangkat TV Anda:

  1. Di Android Studio, pilih project Anda dan klik Jalankan dari toolbar.
  2. Di jendela Select Deployment Target, pilih perangkat TV Anda, lalu klik OK.

Menjalankan di perangkat virtual

AVD Manager di Android SDK menyediakan definisi perangkat yang memungkinkan Anda membuat perangkat TV virtual untuk menjalankan dan untuk menguji aplikasi Anda.

Untuk membuat perangkat TV virtual:

  1. Mulai AVD Manager. Untuk informasi selengkapnya, lihat Membuat dan mengelola perangkat virtual.
  2. Dalam dialog AVD Manager, klik tab Device Definitions.
  3. Pilih salah satu definisi perangkat Android TV, lalu klik Create AVD.
  4. Pilih opsi emulator dan klik OK untuk membuat AVD.

    Catatan: Untuk mendapatkan performa terbaik perangkat emulator TV, gunakan emulator x86 dan aktifkan opsi Use Host GPU. Gunakan juga akselerasi perangkat virtual saat yang tersedia. Untuk informasi selengkapnya tentang akselerasi hardware emulator, lihat Konfigurasi akselerasi hardware untuk Android Emulator.

Untuk menguji aplikasi Anda di perangkat TV virtual:

  1. Di Android Studio, pilih project Anda dan klik Jalankan dari toolbar.
  2. Di jendela Select Deployment Target, pilih perangkat TV virtual Anda, lalu klik OK.

Untuk informasi selengkapnya tentang penggunaan emulator, lihat Jalankan aplikasi di Android Emulator. Untuk informasi selengkapnya tentang men-deploy aplikasi dari Android Studio ke virtual perangkat Anda, lihat Mendebug aplikasi Anda.

Mengaktifkan aplikasi TV untuk dijalankan sebagai pengalaman instan

Pengalaman instan memudahkan pengguna untuk mencoba aplikasi TV Anda dan dapat membantu meningkatkan adopsi.

Untuk menyiapkan aplikasi TV agar berjalan sebagai aplikasi instan di emulator atau perangkat Android TV, pertama, ikuti petunjuk untuk membuat app bundle yang diaktifkan secara instan.

Berikutnya, di intent-filter untuk aplikasi TV MainActivity, pastikan bahwa LAUNCHER dan LEANBACK_LAUNCHER dideklarasikan di AndroidManifest.xml:

<activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
  </activity>

Aplikasi TV Anda kini dikonfigurasi untuk dijalankan sebagai pengalaman instan.

Menyiapkan aplikasi TV untuk publikasi

Tinjau checklist Aplikasi TV untuk langkah selanjutnya menyiapkan aplikasi TV untuk publikasi dan distribusi.