Saluran di layar utama

Layar utama Android TV, atau cukup layar utama, menyediakan UI yang menampilkan rekomendasi konten sebagai tabel saluran dan program. Setiap baris adalah saluran. Saluran berisi kartu untuk setiap program yang tersedia di saluran itu:

Layar utama TV

Dokumen ini menunjukkan cara menambahkan saluran dan program ke layar utama, mengupdate konten, menangani tindakan pengguna, dan memberikan pengalaman terbaik bagi pengguna Anda. (Jika Anda ingin mempelajari API lebih dalam, coba codelab layar utama dan tonton sesi Android TV I/O 2017.)

Catatan: Saluran rekomendasi hanya tersedia di Android 8.0 (API level 26) dan yang lebih baru. Anda harus menggunakannya untuk memberikan rekomendasi bagi aplikasi yang berjalan di Android 8.0 (API level 26) dan yang lebih baru. Guna menyediakan rekomendasi untuk aplikasi yang berjalan di Android versi sebelumnya, aplikasi Anda harus menggunakan baris rekomendasi sebagai gantinya.

UI layar utama

Aplikasi dapat membuat saluran baru, menambahkan, menghapus, dan memperbarui program di saluran, serta mengontrol urutan program di saluran. Misalnya, aplikasi dapat membuat saluran yang disebut "Yang Baru" dan menampilkan kartu untuk program baru yang tersedia.

Aplikasi tidak dapat mengontrol urutan saluran yang muncul di layar utama. Jika aplikasi Anda membuat saluran baru, layar utama akan menambahkannya ke tombol daftar saluran. Pengguna dapat mengurutkan ulang, menyembunyikan, dan menampilkan saluran.

Saluran Tonton Berikutnya

Saluran Tonton Berikutnya adalah baris kedua yang muncul di layar utama, setelah baris aplikasi. Sistem akan membuat dan menyimpan saluran ini. Aplikasi Anda dapat menambahkan program ke saluran Tonton Berikutnya. Untuk informasi selengkapnya, lihat Menambahkan program ke saluran Tonton Berikutnya.

Saluran aplikasi

Saluran yang dibuat aplikasi Anda semuanya mengikuti siklus proses ini:

  1. Pengguna menemukan saluran di aplikasi dan meminta untuk menambahkannya ke layar utama.
  2. Aplikasi membuat saluran dan menambahkannya ke TvProvider (pada saat ini saluran tidak terlihat).
  3. Aplikasi meminta sistem untuk menampilkan saluran.
  4. Sistem meminta pengguna untuk menyetujui saluran baru.
  5. Saluran baru akan muncul di baris terakhir layar utama.

Saluran default

Aplikasi Anda dapat menawarkan sejumlah saluran untuk ditambahkan pengguna ke layar utama. Pengguna biasanya harus memilih dan menyetujui setiap saluran sebelum muncul di layar utama. Setiap aplikasi memiliki opsi untuk membuat satu saluran default. Saluran default bersifat khusus karena otomatis muncul di layar utama; pengguna tidak perlu memintanya secara eksplisit.

Prasyarat

Layar utama Android TV menggunakan TvProvider API Android untuk mengelola saluran dan program yang dibuat oleh aplikasi Anda. Untuk mengakses data penyedia, tambahkan izin berikut ke manifes aplikasi Anda:

<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

Support library TvProvider mempermudah penggunaan penyedia. Tambahkan ke dependensi di file build.gradle Anda:

Groovy

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

implementation("androidx.tvprovider:tvprovider:1.0.0")

Untuk menangani saluran dan program, pastikan untuk menyertakan impor support library dalam program Anda:

Kotlin

import android.support.media.tv.Channel
import android.support.media.tv.TvContractCompat
import android.support.media.tv.ChannelLogoUtils
import android.support.media.tv.PreviewProgram
import android.support.media.tv.WatchNextProgram

Java

import android.support.media.tv.Channel;
import android.support.media.tv.TvContractCompat;
import android.support.media.tv.ChannelLogoUtils;
import android.support.media.tv.PreviewProgram;
import android.support.media.tv.WatchNextProgram;

Channel

Saluran pertama yang dibuat aplikasi Anda menjadi saluran defaultnya. Saluran default otomatis akan muncul di layar utama. Semua saluran yang Anda buat harus dipilih dan diterima oleh pengguna sebelum saluran tersebut muncul di layar utama.

Membuat saluran

Aplikasi Anda harus meminta sistem untuk menampilkan saluran yang baru ditambahkan hanya saat aplikasi sedang berjalan di latar depan. Hal ini mencegah aplikasi Anda menampilkan dialog yang meminta persetujuan untuk menambahkan saluran saat pengguna menjalankan aplikasi lain. Jika Anda mencoba menambahkan saluran saat berjalan di latar belakang, metode onActivityResult() aktivitas akan menampilkan kode status RESULT_CANCELED.

Untuk membuat saluran, ikuti langkah-langkah berikut:

  1. Buat builder saluran dan tetapkan atributnya. Perhatikan bahwa jenis saluran harus TYPE_PREVIEW. Tambahkan atribut lainnya sesuai kebutuhan.

    Kotlin

    val builder = Channel.Builder()
    // Every channel you create must have the type TYPE_PREVIEW
    builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
            .setDisplayName("Channel Name")
            .setAppLinkIntentUri(uri)
    

    Java

    Channel.Builder builder = new Channel.Builder();
    // Every channel you create must have the type TYPE_PREVIEW
    builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
            .setDisplayName("Channel Name")
            .setAppLinkIntentUri(uri);
    
  2. Masukkan saluran ke penyedia:

    Kotlin

    var channelUri = context.contentResolver.insert(
            TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues())
    

    Java

    Uri channelUri = context.getContentResolver().insert(
            TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues());
    
  3. Anda perlu menyimpan ID saluran untuk menambahkan program ke saluran nanti. Ekstrak ID saluran dari URI yang ditampilkan:

    Kotlin

    var channelId = ContentUris.parseId(channelUri)
    

    Java

    long channelId = ContentUris.parseId(channelUri);
    
  4. Anda harus menambahkan logo untuk saluran. Gunakan Uri atau Bitmap. Ikon logo harus berukuran 80dp x 80dp, dan harus buram. Ini ditampilkan di bawah mask lingkaran:

    Mask ikon layar utama TV

    Kotlin

    // Choose one or the other
    storeChannelLogo(context: Context, channelId: Long, logoUri: Uri) // also works if logoUri is a URL
    storeChannelLogo(context: Context, channelId: Long, logo: Bitmap)
    

    Java

    // Choose one or the other
    storeChannelLogo(Context context, long channelId, Uri logoUri); // also works if logoUri is a URL
    storeChannelLogo(Context context, long channelId, Bitmap logo);
    
  5. Buat saluran default (opsional): Saat aplikasi membuat saluran pertamanya, Anda dapat menjadikannya saluran default sehingga langsung muncul di layar utama tanpa tindakan pengguna apa pun. Saluran lain yang Anda buat tidak akan terlihat sampai pengguna memilihnya secara eksplisit.

    Kotlin

    TvContractCompat.requestChannelBrowsable(context, channelId)
    

    Java

    TvContractCompat.requestChannelBrowsable(context, channelId);
    

  6. Buat saluran default Anda muncul sebelum aplikasi Anda terbuka. Anda dapat membuat perilaku ini terjadi dengan menambahkan BroadcastReceiver yang memproses tindakan android.media.tv.action.INITIALIZE_PROGRAMS, yang dikirim layar utama setelah aplikasi diinstal:
    <receiver
      android:name=".RunOnInstallReceiver"
      android:exported="true">
        <intent-filter>
          <action android:name="android.media.tv.action.INITIALIZE_PROGRAMS" />
          <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </receiver>
    
    Saat melakukan sideload aplikasi selama pengembangan, Anda dapat menguji langkah ini dengan memicu intent melalui adb, dengan your.package.name/.YourReceiverName adalah BroadcastReceiver aplikasi Anda:

    adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \
        your.package.name/.YourReceiverName
    

    Dalam kasus yang jarang terjadi, aplikasi Anda mungkin menerima siaran pada saat yang sama saat pengguna memulai aplikasi. Pastikan kode Anda tidak mencoba menambahkan saluran default lebih dari sekali.

Mengupdate saluran

Mengupdate saluran sangat mirip dengan saat membuatnya.

Gunakan Channel.Builder lainnya untuk menetapkan atribut yang perlu diubah.

Gunakan ContentResolver untuk mengupdate saluran. Gunakan ID saluran yang Anda simpan saat saluran ditambahkan untuk pertama kalinya:

Kotlin

context.contentResolver.update(
        TvContractCompat.buildChannelUri(channelId),
        builder.build().toContentValues(),
        null,
        null
)

Java

context.getContentResolver().update(TvContractCompat.buildChannelUri(channelId),
    builder.build().toContentValues(), null, null);

Untuk mengupdate logo saluran, gunakan storeChannelLogo().

Menghapus saluran

Kotlin

context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)

Java

context.getContentResolver().delete(TvContractCompat.buildChannelUri(channelId), null, null);

Program

Menambahkan program ke saluran aplikasi

Buat PreviewProgram.Builder dan tetapkan atributnya:

Kotlin

val builder = PreviewProgram.Builder()
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId)

Java

PreviewProgram.Builder builder = new PreviewProgram.Builder();
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId);

Tambahkan atribut lain yang bergantung pada jenis program. (Untuk melihat atribut yang tersedia untuk setiap jenis program, lihat tabel di bawah ini.)

Masukkan program ke penyedia:

Kotlin

var programUri = context.contentResolver.insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
        builder.build().toContentValues())

Java

Uri programUri = context.getContentResolver().insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
      builder.build().toContentValues());

Ambil ID program untuk referensi nanti:

Kotlin

val programId = ContentUris.parseId(programUri)

Java

long programId = ContentUris.parseId(programUri);

Menambahkan program ke saluran Tonton Berikutnya

Untuk menyisipkan program ke saluran Tonton Berikutnya, lihat Menambahkan program ke saluran Tonton Berikutnya.

Mengupdate program

Anda dapat mengubah informasi program. Misalnya, Anda mungkin ingin mengupdate harga sewa untuk sebuah film, atau mengupdate status progres yang menunjukkan jumlah program yang ditonton pengguna.

Gunakan PreviewProgram.Builder untuk menetapkan atribut yang perlu Anda ubah, lalu panggil getContentResolver().update untuk mengupdate program. Tentukan ID program yang Anda simpan saat program ditambahkan untuk pertama kali:

Kotlin

context.contentResolver.update(
        TvContractCompat.buildPreviewProgramUri(programId),
                builder.build().toContentValues(), null, null
)

Java

context.getContentResolver().update(TvContractCompat.buildPreviewProgramUri(programId),
    builder.build().toContentValues(), null, null);

Menghapus program

Kotlin

context.contentResolver
        .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)

Java

context.getContentResolver().delete(TvContractCompat.buildPreviewProgramUri(programId), null, null);

Menangani tindakan pengguna

Aplikasi Anda dapat membantu pengguna menemukan konten dengan menyediakan UI untuk menampilkan dan menambahkan saluran. Aplikasi Anda juga harus menangani interaksi dengan saluran setelah muncul di layar utama.

Menemukan dan menambahkan saluran

Aplikasi Anda dapat menyediakan elemen UI yang memungkinkan pengguna memilih dan menambahkan salurannya (misalnya, tombol yang meminta untuk menambahkan saluran).

Setelah pengguna meminta saluran tertentu, jalankan kode ini untuk mendapatkan izin pengguna untuk menambahkannya ke UI layar utama:

Kotlin

val intent = Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE)
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId)
try {
  activity.startActivityForResult(intent, 0)
} catch (e: ActivityNotFoundException) {
  // handle error
}

Java

Intent intent = new Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE);
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId);
try {
   activity.startActivityForResult(intent, 0);
} catch (ActivityNotFoundException e) {
  // handle error
}

Sistem menampilkan dialog yang meminta pengguna untuk menyetujui saluran. Tangani hasil permintaan dalam metode onActivityResult aktivitas Anda (Activity.RESULT_CANCELED atau Activity.RESULT_OK).

Peristiwa layar utama Android TV

Saat pengguna berinteraksi dengan saluran/program yang dipublikasikan oleh aplikasi, layar utama akan mengirimkan intent ke aplikasi:

  • Layar utama mengirimkan Uri yang disimpan di atribut APP_LINK_INTENT_URI saluran ke aplikasi saat pengguna memilih logo saluran. Aplikasi cukup meluncurkan UI utamanya atau tampilan terkait saluran yang dipilih.
  • Layar utama mengirimkan Uri yang tersimpan di atribut INTENT_URI program ke aplikasi saat pengguna memilih program. Aplikasi akan memutar konten yang dipilih.
  • Pengguna dapat menunjukkan bahwa mereka tidak lagi tertarik dengan suatu program dan ingin program tersebut dihapus dari UI layar utama. Sistem akan menghapus program dari UI dan mengirimkan intent ke aplikasi yang memiliki program (android.media.tv.ACTION_PR_PROGRAM_BROWSABLE_DISABLED atau android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) dengan ID program. Aplikasi harus menghapus program dari penyedia dan TIDAK boleh memasukkannya kembali.

Pastikan untuk membuat filter intent untuk semua Uris yang dikirimkan layar utama untuk interaksi pengguna; misalnya:

<receiver
   android:name=".WatchNextProgramRemoved"
   android:enabled="true"
   android:exported="true">
   <intent-filter>
       <action android:name="android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED" />
   </intent-filter>
</receiver>

Praktik terbaik

  • Beberapa aplikasi TV mengharuskan pengguna untuk login. Dalam hal ini, BroadcastReceiver yang memproses android.media.tv.action.INITIALIZE_PROGRAMS harus menyarankan konten saluran untuk pengguna yang tidak diautentikasi.Misalnya, aplikasi Anda awalnya dapat menampilkan konten terbaik atau konten populer saat ini. Setelah pengguna masuk, aplikasi dapat menampilkan konten yang dipersonalisasi. Ini adalah peluang besar bagi aplikasi untuk meng-upsell pengguna sebelum login.
  • Jika aplikasi tidak berjalan di latar depan dan Anda perlu mengupdate saluran atau program, gunakan JobScheduler untuk menjadwalkan pekerjaan (lihat: JobScheduler dan JobService).
  • Sistem dapat mencabut izin penyedia aplikasi jika aplikasi Anda berperilaku tidak semestinya (misalnya: terus mengirim spamming data ke penyedia). Pastikan Anda menggabungkan kode yang mengakses penyedia dengan klausa try-catch untuk menangani pengecualian keamanan.
  • Sebelum memperbarui program dan saluran, buat kueri kepada penyedia untuk mengetahui data yang perlu Anda perbarui dan rekonsiliasi data tersebut. Misalnya, tidak perlu mengupdate program yang ingin dihapus pengguna dari UI. Gunakan tugas latar belakang yang menyisipkan/memperbarui data Anda ke penyedia setelah membuat kueri untuk data yang ada, lalu meminta persetujuan untuk saluran Anda. Anda dapat menjalankan tugas ini saat aplikasi dimulai dan kapan pun aplikasi perlu mengupdate datanya.

    Kotlin

    context.contentResolver
      .query(
          TvContractCompat.buildChannelUri(channelId),
              null, null, null, null).use({
                  cursor-> if (cursor != null and cursor.moveToNext()) {
                               val channel = Channel.fromCursor(cursor)
                               if (channel.isBrowsable()) {
                                   //update channel's programs
                               }
                           }
              })
    

    Java

    try (Cursor cursor = context.getContentResolver()
          .query(
              TvContractCompat.buildChannelUri(channelId),
              null,
              null,
              null,
              null)) {
                  if (cursor != null && cursor.moveToNext()) {
                      Channel channel = Channel.fromCursor(cursor);
                      if (channel.isBrowsable()) {
                          //update channel's programs
                      }
                  }
              }
    
  • Gunakan Uri unik untuk semua gambar (logo, ikon, gambar konten) Pastikan untuk menggunakan Uri yang berbeda saat Anda memperbarui gambar. Semua gambar di-cache. Jika tidak mengubah Uri saat Anda mengubah gambar, gambar lama akan terus muncul.

  • Ingat bahwa klausa WHERE tidak diizinkan dan panggilan ke penyedia dengan klausa WHERE akan menampilkan pengecualian keamanan.

Atribut

Bagian ini menjelaskan atribut saluran dan program secara terpisah.

Atribut saluran

Anda harus menentukan atribut ini untuk setiap saluran:

Atribut Catatan
TYPE tetapkan ke TYPE_PREVIEW.
DISPLAY_NAME tetapkan ke nama saluran.
APP_LINK_INTENT_URI Saat pengguna memilih logo saluran, sistem akan mengirimkan intent untuk memulai aktivitas yang menyajikan konten yang relevan dengan saluran. Tetapkan atribut ke Uri yang digunakan dalam filter intent untuk aktivitas itu.

Selain itu, saluran juga memiliki enam kolom yang diperuntukkan untuk penggunaan aplikasi internal. Kolom tersebut dapat digunakan untuk menyimpan kunci atau nilai yang dapat membantu aplikasi memetakan saluran ke struktur data internalnya:

  • INTERNAL_PROVIDER_ID
  • INTERNAL_PROVIDER_DATA
  • INTERNAL_PROVIDER_FLAG1
  • INTERNAL_PROVIDER_FLAG2
  • INTERNAL_PROVIDER_FLAG3
  • INTERNAL_PROVIDER_FLAG4

Atribut program

Lihat halaman individu untuk atribut bagi setiap jenis program:

Contoh Kode

Untuk mempelajari lebih lanjut cara membuat aplikasi yang berinteraksi dengan layar utama dan menambahkan saluran serta program ke layar utama Android TV, lihat codelab layar utama kami.