Ana ekranda kanallar

Android TV ana ekranı, önerilen içerikleri kanallar ve programlar tablosu olarak gösteren bir kullanıcı arayüzü sunar. Her satır bir kanalı temsil eder. Kanallarda, ilgili kanalda bulunan her program için kartlar yer alır:

Bu belgede, ana ekrana nasıl kanal ve program ekleyeceğiniz, içerikleri nasıl güncelleyeceğiniz, kullanıcı işlemlerini nasıl yöneteceğiniz ve kullanıcılarınıza en iyi deneyimi nasıl sunacağınız açıklanmaktadır. (API hakkında daha fazla bilgi edinmek isterseniz ana ekran codelab'ini deneyin ve I/O 2017 Android TV oturumunu izleyin.)

Ana ekran kullanıcı arayüzü

Uygulamalar yeni kanallar oluşturabilir, bir kanaldaki programları ekleyebilir, kaldırabilir ve güncelleyebilir, ayrıca bir kanaldaki programların sırasını kontrol edebilir. Örneğin, bir uygulama "Yenilikler" adlı bir kanal oluşturabilir ve yeni kullanıma sunulan programların kartlarını gösterebilir.

Uygulamalar, kanalların ana ekranda görünme sırasını kontrol edemez. Uygulamanız yeni bir kanal oluşturduğunda ana ekran bu kanalı kanal listesinin en altına ekler. Kullanıcı kanalları yeniden sıralayabilir, gizleyebilir ve gösterebilir.

Sıradaki Video kanalı

Sıradaki Video kanalı, ana ekranda uygulamalar satırından sonra görünen ikinci satırdır. Bu kanal, sistem tarafından oluşturulur ve yönetilir. Uygulamanız, Sıradaki Video kanalına program ekleyebilir. Daha fazla bilgi için Sıradaki Video kanalına program ekleme başlıklı makaleyi inceleyin.

Uygulama kanalları

Uygulamanızın oluşturduğu kanalların tümü şu yaşam döngüsünü izler:

1. Kullanıcı, uygulamanızda bir kanal keşfeder ve bu kanalı ana ekrana eklemek ister.
2. Uygulama, kanalı oluşturur ve TvProvider uygulamasına ekler (bu noktada kanal görünür değildir).
3. Uygulama, sistemden kanalı göstermesini ister.
4. Sistem, kullanıcıdan yeni kanalı onaylamasını ister.
5. Yeni kanal, ana ekranın son satırında görünür.

Varsayılan kanal

Uygulamanız, kullanıcının ana ekrana ekleyebileceği istediğiniz sayıda kanal sunabilir. Kullanıcının genellikle her kanalı ana ekranda görünmeden önce seçip onaylaması gerekir. Her uygulamada bir varsayılan kanal oluşturma seçeneği vardır. Varsayılan kanal, ana ekranda otomatik olarak göründüğü için özeldir. Kullanıcının bunu açıkça istemesi gerekmez.

Ön koşullar

Android TV ana ekranı, uygulamanızın oluşturduğu kanalları ve programları yönetmek için Android'in TvProvider API'lerini kullanır. Sağlayıcının verilerine erişmek için uygulamanızın manifest dosyasına aşağıdaki izni ekleyin:

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

TvProvider destek kitaplığı, sağlayıcının kullanımını kolaylaştırır. build.gradle dosyanızdaki bağımlılıklara ekleyin:

implementation 'androidx.tvprovider:tvprovider:1.0.0'

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

Kanallar ve programlarla çalışmak için programınıza aşağıdaki destek kitaplığı içe aktarma işlemlerini eklediğinizden emin olun:

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;

Kanallar

Uygulamanızın oluşturduğu ilk kanal, varsayılan kanalı olur. Varsayılan kanal, ana ekranda otomatik olarak görünür. Oluşturduğunuz diğer tüm kanalların ana ekranda görünebilmesi için kullanıcı tarafından seçilmesi ve kabul edilmesi gerekir.

Kanal oluşturma

Uygulamanız, sistemden yeni eklenen kanalları yalnızca ön planda çalışırken göstermesini istemelidir. Bu sayede, kullanıcı farklı bir uygulama çalıştırırken uygulamanızın kanalınızı eklemek için onay isteyen bir iletişim kutusu göstermesi engellenir. Arka planda çalışırken kanal eklemeye çalışırsanız etkinliğin onActivityResult() yöntemi RESULT_CANCELED durum kodunu döndürür.

Kanal oluşturmak için aşağıdaki adımları uygulayın:

1. Kanal oluşturucu oluşturun ve özelliklerini ayarlayın. Kanal türünün TYPE_PREVIEW olması gerektiğini unutmayın. Gerektiği şekilde daha fazla özellik ekleyin.

   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. Kanalı sağlayıcıya ekleyin:

   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. Kanala daha sonra program eklemek için kanal kimliğini kaydetmeniz gerekir. Döndürülen URI'dan kanal kimliğini ayıklayın:

   Kotlin

   var channelId = ContentUris.parseId(channelUri)
   

   Java

   long channelId = ContentUris.parseId(channelUri);
   

4. Kanalınız için bir logo eklemeniz gerekir. Uri veya Bitmap kullanın. Logo simgesi 80 dp x 80 dp boyutunda ve opak olmalıdır. Dairesel bir maske altında gösterilir:

   

   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. Varsayılan kanalı oluşturma (isteğe bağlı): Uygulamanız ilk kanalını oluşturduğunda, bunu varsayılan kanal yaparak herhangi bir kullanıcı işlemi olmadan hemen ana ekranda görünmesini sağlayabilirsiniz. Oluşturduğunuz diğer kanallar, kullanıcı tarafından açıkça seçilene kadar görünmez.

   Kotlin

   TvContractCompat.requestChannelBrowsable(context, channelId)
   

   Java

   TvContractCompat.requestChannelBrowsable(context, channelId);
   

6. Varsayılan kanalınızın, uygulamanız açılmadan önce görünmesini sağlayın. Uygulama yüklendikten sonra ana ekranın gönderdiği android.media.tv.action.INITIALIZE_PROGRAMS işlemini dinleyen bir BroadcastReceiver ekleyerek bu davranışı gerçekleştirebilirsiniz:

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

   Geliştirme sırasında uygulamanızı başka bir kaynaktan yüklerken adb üzerinden intent'i tetikleyerek bu adımı test edebilirsiniz. Burada your.package.name/.YourReceiverName, uygulamanızın BroadcastReceiver değeridir:

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

   Nadir durumlarda uygulamanız, kullanıcı uygulamanızı başlattığı anda yayını alabilir. Kodunuzun varsayılan kanalı birden fazla kez eklemeye çalışmadığından emin olun.

Kanal güncelleme

Kanalları güncelleme işlemi, kanal oluşturma işlemine çok benzer.

Değiştirilmesi gereken özellikleri ayarlamak için başka bir Channel.Builder kullanın.

Kanalı güncellemek için ContentResolver kullanın. Kanal ilk eklendiğinde kaydettiğiniz kanal kimliğini kullanın:

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

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

Bir kanalın logosunu güncellemek için storeChannelLogo() komutunu kullanın.

Kanal silme

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

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

Programlar

Programlar, bir kanalda gösterilen bağımsız içerik kartlarıdır. Programları hem uygulamanızın özel kanallarında hem de sistem tarafından yönetilen Sıradaki Video kanalında yayınlayabilirsiniz.

Uygulama kanalına program ekleme

Bir PreviewProgram.Builder oluşturun ve özelliklerini ayarlayın:

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

Programın türüne göre daha fazla özellik ekleyin. (Her program türü için kullanılabilen özellikleri görmek istiyorsanız aşağıdaki tablolara bakın.)

Programı sağlayıcıya ekleyin:

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

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

Daha sonra kullanmak üzere program kimliğini alın:

val programId = ContentUris.parseId(programUri)

long programId = ContentUris.parseId(programUri);

Sıradaki Video kanalına program ekleme

Sıradaki Video kanalına program eklemek için Sıradaki Video kanalına program ekleme başlıklı makaleyi inceleyin.

Program güncelleme

Bir programın bilgilerini değiştirebilirsiniz. Örneğin, bir filmin kiralama fiyatını güncellemek veya kullanıcının bir programın ne kadarını izlediğini gösteren ilerleme çubuğunu güncellemek isteyebilirsiniz.

Değiştirmeniz gereken özellikleri ayarlamak için PreviewProgram.Builder kullanın, ardından programı güncellemek için getContentResolver().update yöntemini çağırın. Program ilk eklendiğinde kaydettiğiniz program kimliğini belirtin:

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

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

Program silme

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

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

Kullanıcı işlemlerini işleme

Uygulamanız, kanalları görüntülemek ve eklemek için bir kullanıcı arayüzü sağlayarak kullanıcıların içerik keşfetmesine yardımcı olabilir. Uygulamanız, ana ekranda göründükten sonra kanallarınızla olan etkileşimleri de işlemelidir.

Kanalları keşfetme ve ekleme

Uygulamanız, kullanıcının kanallarını seçip eklemesine olanak tanıyan bir kullanıcı arayüzü öğesi sağlayabilir (örneğin, kanal eklemeyi isteyen bir düğme).

Kullanıcı belirli bir kanal için istekte bulunduktan sonra, kullanıcının kanalı ana ekran kullanıcı arayüzüne ekleme iznini almak için bu kodu yürütün:

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, kullanıcıdan kanalı onaylamasını isteyen bir iletişim kutusu gösterir. İsteğin sonucunu, etkinliğinizin onActivityResult yönteminde (Activity.RESULT_CANCELED veya Activity.RESULT_OK) işleyin.

Android TV ana ekran etkinlikleri

Kullanıcı, uygulama tarafından yayınlanan programlar ve kanallarla etkileşimde bulunduğunda ana ekran, uygulamaya intent'ler gönderir:

• Kullanıcı kanalın logosunu seçtiğinde ana ekran, kanalın APP_LINK_INTENT_URI özelliğinde depolanan Uri değerini uygulamaya gönderir. Uygulama yalnızca ana kullanıcı arayüzünü veya seçilen kanalla ilgili bir görünümü başlatmalıdır.
• Ana ekran, kullanıcı bir program seçtiğinde programın INTENT_URI özelliğinde depolanan Uri değerini uygulamaya gönderir. Uygulama, seçilen içeriği oynatmalıdır.
• Kullanıcı, artık bir programla ilgilenmediğini ve programın ana ekranın kullanıcı arayüzünden kaldırılmasını istediğini belirtebilir. Sistem, programı kullanıcı arayüzünden kaldırır ve programın sahibi olan uygulamaya programın kimliğini içeren bir intent (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED veya android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) gönderir. Uygulama, programı sağlayıcıdan kaldırmalı ve yeniden eklememelidir.

Ana ekranın kullanıcı etkileşimleri için gönderdiği tüm Uris için intent filtreleri oluşturduğunuzdan emin olun. Örneğin:

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

Göz önünde bulundurulacak diğer noktalar

• Birçok TV uygulamasında kullanıcıların giriş yapması gerekir. Bu durumda, android.media.tv.action.INITIALIZE_PROGRAMS için dinleme yapan BroadcastReceiver, kimliği doğrulanmamış kullanıcılar için kanal içeriği önermelidir. Örneğin, uygulamanız başlangıçta en iyi içeriği veya o anda popüler olan içeriği gösterebilir. Kullanıcı giriş yaptıktan sonra kişiselleştirilmiş içerik gösterebilir. Bu, uygulamaların kullanıcılar giriş yapmadan önce daha yüksek fiyatlı ürün almaya ikna etmesi için harika bir fırsattır.
• Uygulamanız ön planda değilken bir kanalı veya programı güncellemeniz gerektiğinde işi planlamak için JobScheduler kullanın (JobScheduler ve JobService bölümlerine bakın).
• Uygulamanız hatalı davranırsa (ör. sağlayıcıya sürekli olarak spam veri gönderirse) sistem, uygulamanızın sağlayıcı izinlerini iptal edebilir. Sağlayıcıya erişen kodu, güvenlik istisnalarını işlemek için try-catch ifadeleriyle sarmaladığınızdan emin olun.

• Programları ve kanalları güncellemeden önce sağlayıcıdan güncellemeniz gereken verileri isteyin ve verileri mutabık kılın. Örneğin, kullanıcının kullanıcı arayüzünden kaldırılmasını istediği bir programı güncellemeye gerek yoktur. Mevcut verileri sorguladıktan ve kanallarınız için onay istedikten sonra verilerinizi sağlayıcıya ekleyen veya güncelleyen bir arka plan işi kullanın. Bu işi, uygulama başlatıldığında ve uygulamanın verilerini güncellemesi gerektiğinde çalıştırabilirsiniz.

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

• Tüm resimler (logolar, simgeler, içerik resimleri) için benzersiz URI'ler kullanın. Bir resmi güncellerken farklı bir URI kullandığınızdan emin olun. Tüm resimler önbelleğe alınır. Resmi değiştirirken URI'yi değiştirmezseniz eski resim görünmeye devam eder.

• WHERE yan tümcelerine izin verilmediğini ve WHERE yan tümceleriyle sağlayıcılara yapılan çağrıların güvenlik istisnası oluşturacağını unutmayın.

Özellikler

Bu bölümde kanal ve program özellikleri ayrı ayrı açıklanmaktadır.

Kanal özellikleri

Her kanal için şu özellikleri belirtmeniz gerekir:

Ayrıca, bir kanalda dahili uygulama kullanımı için ayrılmış altı alan da bulunur. Bu alanlar, uygulamanın kanalı dahili veri yapısıyla eşlemesine yardımcı olabilecek anahtarları veya diğer değerleri depolamak için kullanılabilir:

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

Program özellikleri

Her program türünün özelliklerini görmek için ilgili sayfalara bakın:

• Video Programı Özellikleri
• Ses Programı Özellikleri
• Oyun Programı Özellikleri
• Sıradaki Video Programı Özellikleri

Örnek Kod

Ana ekranla etkileşim kuran uygulamalar oluşturma ve Android TV ana ekranına kanal ve program ekleme hakkında daha fazla bilgi edinmek için ana ekran codelab'imize göz atın.