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ılabilir programlar için 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.
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:
- Kullanıcı, uygulamanızda bir kanal keşfeder ve bu kanalı ana ekrana eklemek ister.
- Uygulama, kanalı oluşturur ve
TvProvider'e ekler (bu noktada kanal görünür değildir). - Uygulama, sistemden kanalı göstermesini ister.
- Sistem, kullanıcıdan yeni kanalı onaylamasını ister.
- 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:
Modern
implementation 'androidx.tvprovider:tvprovider:1.0.0'
Kotlin
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
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:
Kanal oluşturucu oluşturun ve özelliklerini ayarlayın. Kanal türünün
TYPE_PREVIEWolması gerektiğini unutmayın. Gerektiği şekilde daha fazla özellik ekleyin.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)
Kanalı sağlayıcıya ekleyin:
var channelUri = context.contentResolver.insert( TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues() )
Kanala daha sonra program eklemek için kanal kimliğini kaydetmeniz gerekir. Döndürülen URI'dan kanal kimliğini ayıklayın:
var channelId = ContentUris.parseId(channelUri)
Kanalınız için bir logo eklemeniz gerekir.
UriveyaBitmapkullanın. Logo simgesi 80 dp x 80 dp boyutunda ve opak olmalıdır. Dairesel bir maske altında gösterilir:
// Choose one or the other. storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL. storeChannelLogo(context, channelId, logo)
Varsayılan kanalı oluşturun (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ünür olmaz.
TvContractCompat.requestChannelBrowsable(context, channelId)
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_PROGRAMSişlemini dinleyen birBroadcastReceiverekleyerek 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
BroadcastReceiverdeğeridir:adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \ your.package.name/.YourReceiverNameNadir durumlarda, uygulamanız yayını kullanıcı uygulamanızı başlattığı anda 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 )
Bir kanalın logosunu güncellemek için storeChannelLogo() kullanın.
Kanal silme
context.contentResolver.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)
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() )
Daha sonra kullanmak üzere program kimliğini alın:
val 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 bölümüne bakın.
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 )
Program silme
context.contentResolver .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, ana ekran kullanıcı arayüzüne eklemek üzere kullanıcının 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
}
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
Urideğ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
Urideğ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_PROGRAMSiçin dinleme yapanBroadcastReceiver, 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 İç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
JobSchedulerkullanın (JobSchedulerveJobServicebö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. Güvenlik istisnalarını işlemek için sağlayıcıya erişen kodu 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 && cursor.moveToNext()) { val 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:
| Özellik | Notlar |
|---|---|
| TÜR | TYPE_PREVIEW olarak ayarlandı. |
| DISPLAY_NAME | kanalın adı olarak ayarlanır. |
| APP_LINK_INTENT_URI | Kullanıcı kanalın logosunu seçtiğinde sistem, kanalla alakalı içerik sunan bir etkinliği başlatmak için bir intent gönderir. Bu özelliği, söz konusu etkinliğin intent filtresinde kullanılan URI'ye ayarlayın. |
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şleştirmesine 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.