Saluran di layar utama

Layar utama Android TV menyediakan UI yang menampilkan konten yang direkomendasikan sebagai tabel saluran dan program. Setiap baris adalah saluran. Saluran berisi kartu untuk setiap program yang tersedia di saluran tersebut:

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

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 bernama "Yang Baru" dan menampilkan kartu untuk program yang baru tersedia.

Aplikasi tidak dapat mengontrol urutan saluran yang muncul di layar utama. Saat aplikasi Anda membuat saluran baru, layar utama akan menambahkannya ke bagian bawah 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 mengetahui 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 Anda dan meminta untuk menambahkannya ke layar utama.
2. Aplikasi membuat saluran dan menambahkannya ke TvProvider (pada tahap 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 saluran tersebut 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 API TvProvider Android untuk mengelola saluran dan program yang dibuat 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 dalam file build.gradle Anda:

implementation 'androidx.tvprovider:tvprovider:1.0.0'

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

Untuk menggunakan channel dan program, pastikan untuk menyertakan impor library dukungan ini dalam program Anda:

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

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 akan otomatis muncul di layar utama. Semua saluran lain yang Anda buat harus dipilih dan diterima oleh pengguna sebelum dapat muncul di layar utama.

Membuat saluran

Aplikasi Anda harus meminta sistem untuk menampilkan saluran yang baru ditambahkan hanya saat 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 harus menyimpan ID channel untuk menambahkan program ke channel 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 80 dp x 80 dp, dan harus buram. Ikon ini ditampilkan di bawah mask melingkar:

   

   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 saluran tersebut langsung muncul di layar utama tanpa tindakan pengguna apa pun. Saluran lain yang Anda buat tidak akan terlihat hingga 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 oleh 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 Anda. 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 channel yang Anda simpan saat channel pertama kali ditambahkan:

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

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

Untuk mengupdate logo saluran, gunakan storeChannelLogo().

Menghapus saluran

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

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

Program

Program adalah kartu konten individual yang ditampilkan dalam saluran. Anda dapat memublikasikan program ke saluran kustom aplikasi dan saluran Tonton Berikutnya yang dikelola sistem.

Menambahkan program ke saluran aplikasi

Buat PreviewProgram.Builder dan tetapkan atributnya:

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

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.)

Masukkan program ke penyedia:

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

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

Ambil ID program untuk referensi nanti:

val programId = ContentUris.parseId(programUri)

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 memperbarui harga sewa sebuah film, atau memperbarui status progres yang menunjukkan seberapa jauh bagian program yang telah ditonton pengguna.

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

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

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

Menghapus program

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

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 saluran tersebut 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:

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
}

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 program dan saluran yang dipublikasikan oleh aplikasi, layar utama akan mengirimkan intent ke aplikasi:

• Layar utama mengirimkan Uri yang disimpan dalam atribut APP_LINK_INTENT_URI saluran ke aplikasi saat pengguna memilih logo saluran. Aplikasi hanya perlu meluncurkan UI utamanya atau tampilan yang terkait dengan saluran yang dipilih.
• Layar utama mengirimkan Uri yang disimpan dalam 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 menghapusnya dari UI layar utama. Sistem akan menghapus program dari UI dan mengirimkan intent ke aplikasi yang memiliki program tersebut (android.media.tv.ACTION_PREVIEW_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 menyisipkannya kembali.

Pastikan untuk membuat filter intent untuk semua Uris yang dikirim 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>

Pertimbangan tambahan

• Beberapa aplikasi TV mengharuskan pengguna untuk login. Dalam hal ini, BroadcastReceiver yang memproses android.media.tv.action.INITIALIZE_PROGRAMS harus menyarankan konten channel untuk pengguna yang tidak diautentikasi. Misalnya, aplikasi Anda dapat menampilkan konten terbaik atau konten yang sedang populer terlebih dahulu. Setelah pengguna login, aplikasi dapat menampilkan konten yang dipersonalisasi. Ini adalah peluang bagus bagi aplikasi untuk melakukan up-sell kepada pengguna sebelum mereka login.
• Jika aplikasi Anda tidak berada 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 Anda jika aplikasi Anda berperilaku buruk (misalnya: terus-menerus mengirim spam data ke penyedia). Pastikan Anda menggabungkan kode yang mengakses penyedia dengan klausa try-catch untuk menangani pengecualian keamanan.

• Sebelum mengupdate program dan saluran, buat kueri penyedia untuk data yang perlu Anda update dan rekonsiliasi data. Misalnya, tidak perlu memperbarui program yang ingin dihapus pengguna dari UI. Gunakan tugas latar belakang yang menyisipkan atau 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 setiap kali aplikasi perlu memperbarui datanya.

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
                                }
                            }
              })

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 mengupdate gambar. Semua gambar di-cache. Jika Anda tidak mengubah Uri saat 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:

Selain itu, saluran juga memiliki enam kolom yang diperuntukkan untuk penggunaan aplikasi internal. Kolom ini dapat digunakan untuk menyimpan kunci atau nilai lain 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:

• Atribut Program Video
• Atribut Program Audio
• Atribut Program Game
• Atribut Program Tonton Berikutnya

Kode Contoh

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