Ana ekranda kanallar

Android TV ana ekranı veya kısaca ana ekran, önerilen içeriği kanallar ve programlar tablosu olarak gösteren bir kullanıcı arayüzü sağlar. Her satır bir kanaldır. Bir kanal, ilgili kanalda mevcut olan her program için kartlar içerir:

TV ana ekranı

Bu dokümanda, ana ekrana nasıl kanal ve program ekleneceği, içeriğin nasıl güncelleneceği, kullanıcı işlemlerinin nasıl yönetileceği ve kullanıcılarınıza en iyi deneyimin nasıl sunulacağı gösterilmektedir. (API'nin ayrıntılarına inmek isterseniz ana ekran codelab'ini deneyin ve I/O 2017 Android TV oturumunu izleyin.)

Not: Öneri kanalları yalnızca Android 8.0 (API düzeyi 26) ve sonraki sürümlerde kullanılabilir. Bunları, Android 8.0 (API düzeyi 26) ve sonraki sürümlerde çalışan uygulamalara yönelik öneriler sağlamak için kullanmanız gerekir. Android'in önceki sürümlerinde çalışan uygulamalarla ilgili öneriler sağlamak için uygulamanızın bunun yerine öneri satırını kullanması gerekir.

Ana ekran kullanıcı arayüzü

Uygulamalar yeni kanallar oluşturabilir, kanaldaki programları ekleyebilir, kaldırabilir, güncelleyebilir ve kanaldaki programların sırasını kontrol edebilir. Örneğin, bir uygulama "Yenilikler" adında bir kanal oluşturabilir ve yeni kullanılabilen programlara ilişkin kartlar 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.

Sonrakini İzle kanalı

Sonrakini İzle kanalı, ana ekranda uygulama satırından sonra görünen ikinci satırdır. Bu kanalı sistem oluşturur ve yönetir. Uygulamanız, Sonrakini İzle kanalına program ekleyebilir. Daha fazla bilgi için Sonrakini İzle kanalına program ekleme bölümüne bakın.

Uygulama kanalları

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

  1. Kullanıcı, uygulamanızda bir kanal keşfeder ve bu kanalı ana ekrana eklemek ister.
  2. Uygulama, kanalı oluşturur ve TvProvider içine ekler (bu noktada kanal görünmez).
  3. Uygulama, sistemden kanalı görüntülemesini 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 ekleyebilmesi için istediğiniz sayıda kanal sunabilir. Genellikle ana ekranda görünmeden önce her bir kanalı kullanıcının seçip onaylaması gerekir. Her uygulama, bir varsayılan kanal oluşturma seçeneğine sahiptir. Varsayılan kanal özeldir, çünkü ana ekranda otomatik olarak görünür ve kullanıcının açık bir şekilde istekte bulunması 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 aşağıdaki izni uygulamanızın manifest dosyasına 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:

Modern

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

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

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

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;

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 önce kullanıcı tarafından seçilmesi ve kabul edilmesi gerekir.

Kanal oluşturma

Uygulamanız, yeni eklenen kanalları yalnızca ön planda çalışırken sistemden göstermesini istemelidir. Bu durum, 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örüntülemesini engeller. Arka planda çalışırken bir kanal eklemeye çalışırsanız etkinliğin onActivityResult() yöntemi RESULT_CANCELED durum kodunu döndürür.

Kanal oluşturmak için şu adımları uygulayın:

  1. Bir kanal oluşturucu oluşturun ve özelliklerini ayarlayın. Kanal türünün TYPE_PREVIEW olması gerektiğini unutmayın. Gerektiğinde 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'den kanal kimliğini çıkarı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. Yuvarlak bir maskenin altında gösterilir:

    TV ana ekran simgesi maskesi

    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, herhangi bir kullanıcı işlemi olmadan hemen ana ekranda görünmesi için kanalı varsayılan kanal yapabilirsiniz. Oluşturduğunuz diğer kanallar, kullanıcı açık bir şekilde seçene 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ışın gerçekleşmesini sağlayabilirsiniz:
    <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 cihazdan yüklerken amacı, adb aracılığıyla 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ı bir defadan fazla eklemediğinden emin olun.

Kanal güncelleme

Kanalların güncellenmesi kanal oluşturmaya çok benzer.

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

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

Kotlin

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

Java

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

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

Kanal silme

Kotlin

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

Java

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

Programlar

Uygulama kanalına program ekleme

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

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

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

Programı sağlayıcıya ekleyin:

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

Daha sonra başvurmak için program kimliğini alın:

Kotlin

val programId = ContentUris.parseId(programUri)

Java

long programId = ContentUris.parseId(programUri);

Sonrakini İzle kanalına program ekleme

Sonrakini İzle kanalına program eklemek için Sonrakini İzle kanalına program ekleme konusuna bakın.

Program güncelleme

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

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

Kotlin

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

Java

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

Program silme

Kotlin

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

Java

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şfetmelerine 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 (ör. kanalın eklenmesini isteyen bir düğme) sağlayabilir.

Kullanıcının belirli bir kanalı istemesinin ardından, kullanıcının kanalı ana ekran kullanıcı arayüzüne ekleme iznini almak için şu kodu çalıştırın:

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, kullanıcıdan kanalı onaylamasını isteyen bir iletişim kutusu görüntüler. İ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 programlarla/kanallarla etkileşimde bulunduğunda ana ekran, uygulamaya niyet gönderir:

  • Kullanıcı, kanalın logosunu seçtiğinde ana ekran, kanalın APP_LINK_INTENT_URI özelliğinde depolanan Uri bilgisini uygulamaya gönderir. Uygulamanın sadece ana kullanıcı arayüzünü veya seçilen kanalla ilgili bir görünümü başlatması gerekir.
  • Kullanıcı bir program seçtiğinde ana ekran, bir programın INTENT_URI özelliğinde depolanan Uri bilgisini uygulamaya gönderir. Uygulama, seçilen içeriği oynatır.
  • Kullanıcı artık bir programla ilgilenmediğini belirtebilir ve programın ana ekranın kullanıcı arayüzünden kaldırılmasını isteyebilir. Sistem, programı kullanıcı arayüzünden kaldırır ve programın kimliğiyle birlikte programa sahip olan uygulamaya bir amaç (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 YENİDEN EKLEMEMELİDİR.

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>

En iyi uygulamalar

  • Birçok TV uygulaması kullanıcıların giriş yapmasını gerektirir. Bu durumda, android.media.tv.action.INITIALIZE_PROGRAMS politikasını dinleyen 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çerikler gösterilebilir. Bu, uygulamaların kullanıcılara giriş yapmadan önce daha yüksek fiyatlı ürün satmaları için harika bir fırsattır.
  • Uygulamanız ön planda değilse ve bir kanalı veya programı güncellemeniz gerektiğinde, işi planlamak için JobScheduler öğesini kullanın (bkz: JobScheduler ve JobService).
  • Uygulamanız hatalı davranırsa (örneğin: sağlayıcıya sürekli veri göndererek) sistem uygulamanızın sağlayıcı izinlerini iptal edebilir. Güvenlik istisnalarını ele almak için sağlayıcıya erişen kodu deneme yakalama ifadeleriyle sarmaladığınızdan emin olun.
  • Programları ve kanalları güncellemeden önce, verileri güncellemek ve uzlaştırmak için ihtiyaç duyduğunuz verilerle ilgili olarak sağlayıcıya sorgu gönderin. Ö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 sonra kanallarınız için onay istedikten sonra verilerinizi sağlayıcıya ekleyen/güncelleyen bir arka plan işi kullanın. Bu işi, uygulama başladığında ve uygulamanın verilerini güncellemesi gerektiğinde çalıştırabilirsiniz.

    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
                      }
                  }
              }
    
  • Tüm resimlerde (logolar, simgeler, içerik resimleri) benzersiz bir Uris kullanın. Bir resmi güncellerken farklı bir URI kullandığınızdan emin olun. Tüm görseller önbelleğe alınır. Resmi değiştirirken URI'yı değiştirmezseniz eski resim görünmeye devam eder.

  • WHERE yan tümcelerine izin verilmediğini ve WHERE yan tümcelerine sahip sağlayıcılara yapılan çağrıların bir 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:

Özellik Notlar
TÜR TYPE_PREVIEW olarak ayarlandı.
DISPLAY_NAME kanal adına ayarlayabilirsiniz.
UYGULAMA_LINK_INTENT_URI Kullanıcı kanalın logosunu seçtiğinde sistem, kanalla alakalı içerik sunan bir etkinlik başlatmak için bir niyet gönderir. Bu özelliği, söz konusu etkinliğin intent filtresinde kullanılan URI'ye ayarlayın.

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

  • DAHİLİ_SAĞLAYICI_KİMLİĞİ
  • DAHİLİ_SAĞLAYICI_VERİLERİ
  • DAHİLİ_SAĞLAYICI_FLAG1
  • DAHİLİ_SAĞLAYICI_FLAG2
  • DAHİLİ_SAĞLAYICI_FLAG3
  • DAHİLİ_SAĞLAYICI_FLAG4

Program özellikleri

Her program türünün nitelikleri için ayrı sayfalara bakın:

Örnek Kod

Ana ekranla etkileşimde bulunan ve Android TV ana ekranına kanal ve program ekleyen uygulamalar geliştirme hakkında daha fazla bilgi edinmek için ana ekran codelab'imize göz atın.