TV uygulaması oluşturma ve çalıştırma

TV uygulamaları, telefon ve tablet uygulamalarıyla aynı yapıyı kullanır. Bu benzerlik sayesinde, mevcut uygulamalarınızı TV cihazlarında da çalışacak şekilde değiştirebilir veya Android için uygulama geliştirme konusunda bildiklerinizi kullanarak yeni uygulamalar oluşturabilirsiniz.

Önemli: Uygulamanızın Google Play'de Android TV uygulaması olarak nitelendirilmesi için belirli şartları karşılaması gerekir. Daha fazla bilgi için TV uygulaması kalitesi bölümünde listelenen koşulları inceleyin.

Bu kılavuzda, geliştirme ortamınızı TV uygulamaları oluşturmaya nasıl hazırlayacağınız ve bir uygulamanın TV cihazlarında çalışmasını sağlamak için yapılması gereken minimum değişiklikler açıklanmaktadır.

TV için uygulama tasarlama hakkında bilgi edinmek istiyorsanız TV için tasarım başlıklı makaleyi inceleyin. Ayrıca, Android TV GitHub deposundaki örnek uygulamalara da göz atın.

Medya biçimi desteğini belirleme

Android TV'nin desteklediği codec'ler, protokoller ve biçimler hakkında bilgi edinmek için aşağıdaki dokümanlara göz atın:

• Desteklenen medya biçimleri
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

TV projesi oluşturma

Bu bölümde, mevcut bir Android uygulamasını TV cihazlarında çalışacak şekilde değiştiriyor veya yeni bir TV uygulaması oluşturuyor olmanıza bakılmaksızın TV projesinin nasıl ayarlanacağı açıklanmaktadır. Mevcut bir Android uygulamanız varsa Android TV desteği ekleyerek mevcut uygulama mimarinizi yeniden kullanırken TV için bir kullanıcı arayüzü tasarlayabilirsiniz.

TV cihazlarında çalışan bir uygulama oluştururken kullandığınız iki ana bileşen vardır:

• TV için etkinlik: Uygulama manifestinizde, TV cihazlarında çalışması amaçlanan bir etkinlik bildirin.
• TV kitaplıkları: İsteğe bağlı olarak, bu kılavuzun başka bir bölümünde listelenen TV cihazları için kullanılabilen androidx kitaplıklarından birini veya daha fazlasını ekleyin. Bu kitaplıklar, kullanıcı arayüzleri oluşturmak için widget'lar sağlar.

Ön koşullar

TV için uygulama geliştirmeye başlamadan önce aşağıdaki adımları uygulamanız gerekir:

• SDK araçlarınızı 24.0.0 veya sonraki bir sürüme güncelleyin.
  Güncellenen SDK araçları, TV için uygulamalar oluşturup test etmenize olanak tanır.
• SDK'nızı Android 5.0 (API 21) veya sonraki sürümlerle güncelleyin.
  Güncellenen platform sürümü, TV uygulamaları için yeni API'ler sunar.
• Uygulama projenizi oluşturun veya güncelleyin.
  TV cihazlarına yönelik yeni API'lere erişmek için Android 5.0 (API düzeyi 21) veya sonraki sürümleri hedefleyen bir proje oluşturun ya da mevcut bir projeyi değiştirin.

TV etkinliği bildirme

TV cihazlarında çalışması amaçlanan bir uygulama, manifest dosyasında TV için başlatıcı etkinliği beyan etmelidir. Bunu yapmak için CATEGORY_LEANBACK_LAUNCHER amaç filtresi kullanır. Bu filtre, uygulamanızı TV'de kullanılabilir olarak tanımlar ve Google Play'in uygulamayı TV uygulaması olarak tanımlamasına olanak tanır. Kullanıcı TV'sinin ana ekranında uygulamanızı seçtiğinde bu amaç, hangi etkinliğin başlatılacağını belirler.

Aşağıdaki kod snippet'inde, bu intent filtresinin manifestinize nasıl dahil edileceği gösterilmektedir:

<application
  android:banner="@drawable/banner" >
  ...
  <activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
  </activity>

  <activity
    android:name="com.example.android.TvActivity"
    android:label="@string/app_name"
    android:theme="@style/Theme.Leanback">

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>

  </activity>
</application>

Bu örnekteki ikinci etkinlik manifesti girişi, TV cihazında başlatılacak etkinliğin bu olduğunu belirtir.

Dikkat: CATEGORY_LEANBACK_LAUNCHER intent filtresini uygulamanıza dahil etmezseniz uygulamanız, TV cihazlarında Google Play'i çalıştıran kullanıcılara görünmez. Ayrıca, uygulamanızı geliştirici araçlarını kullanarak TV cihazına yüklediğinizde bu filtre yoksa uygulama, TV kullanıcı arayüzünde görünmez.

TV uygulamanızın kullanıcı arayüzü veya mevcut uygulamanızın TV bölümü, 3 metre uzaklıktaki bir uzaktan kumanda kullanılarak sezgisel gezinme imkanı sunmalıdır. Mevcut bir uygulamayı TV'de kullanılacak şekilde değiştiriyorsanız telefonlar ve tabletler için kullandığınız etkinlik düzenini TV için kullanmayın. TV için uygulama tasarlama yönergeleri hakkında bilgi edinmek için TV için tasarım başlıklı makaleyi inceleyin.

TV cihazı desteğini beyan etme

android.software.leanback özelliğini beyan ederek uygulamanızın Android TV için geliştirildiğini belirtin.

Uygulamanız hem mobil cihazlarda hem de TV'de çalışıyorsa required özellik değerini false olarak ayarlayın. required özellik değerini true olarak ayarlarsanız Google Play, uygulamanızı yalnızca Android TV OS'te kullanılabilir hâle getirir.

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

Dokunmatik ekranın gerekli olmadığını beyan etme

TV cihazlarında çalışması amaçlanan uygulamalarda giriş için dokunmatik ekran kullanılmaz. Bunu netleştirmek için TV uygulamanızın manifestinde android.hardware.touchscreen özelliğinin gerekli olmadığı beyan edilmelidir. Bu ayar, uygulamanızın TV cihazında çalışabileceğini belirtir ve uygulamanızın Google Play'de TV uygulaması olarak kabul edilmesi için gereklidir. Aşağıdaki kod örneğinde bu manifest beyanının nasıl ekleneceği gösterilmektedir:

<manifest>
    <uses-feature android:name="android.hardware.touchscreen"
              android:required="false" />
    ...
</manifest>

Dikkat: Uygulama manifestinizde, bu örnek kodda gösterildiği gibi dokunmatik ekranın gerekli olmadığını beyan etmeniz gerekir. Aksi takdirde, uygulamanız TV cihazlarında Google Play'de görünmez.

Ana ekran simgesi ve banner sağlama

Android TV uygulamaları, her yerelleştirme için hem ana ekran simgesi hem de banner resmi sağlamalıdır. Android TV cihazına bağlı olarak, ana ekrandaki uygulamalar ve oyunlar satırlarında uygulama başlatma noktası olarak simge veya banner kullanılır.

Bunları uygulamanıza eklemek için simgeyi ve banner'ı manifest dosyasında aşağıdaki gibi açıklayın:

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

Ana ekran simgesi

Android TV uygulamaları, tüm Android uygulamaları gibi bir ana ekran simgesi sağlamalıdır. Uygulamanız için mükemmel bir başlangıç noktası tasarlama ve ayrıntılı öğe koşullarıyla ilgili en iyi uygulamalar için Android TV uygulama simgesi ve banner yönergelerine bakın.

Ana ekran banner'ı

Tüm uygulama etkinlikleri için varsayılan bir banner sağlamak üzere android:banner özelliğini <application> etiketiyle veya belirli bir etkinlik için banner sağlamak üzere <activity> etiketiyle birlikte kullanın.

Banner için 320 x 180 piksel boyutunda bir xhdpi kaynağı kullanın. Metin, resme dahil edilmelidir. Uygulamanız birden fazla dilde kullanılabiliyorsa desteklenen her dil için metin içeren ayrı banner sürümleri sağlamanız gerekir.

Başlatıcı rengini değiştirme

Dikkat: Android 12 ve sonraki sürümlerde, SplashScreen platform API'si kullanılarak oluşturulan özel başlangıç ekranı animasyonları Android TV uygulamalarında desteklenmez.

Bir TV uygulaması başlatıldığında sistem, genişleyen ve dolu bir daireye benzeyen bir animasyon gösterir. Bu animasyonun rengini özelleştirmek için TV uygulamanızın veya etkinliğinizin android:colorPrimary özelliğini belirli bir renge ayarlayın. Ayrıca, tema kaynağı XML dosyasından alınan aşağıdaki snippet'te gösterildiği gibi iki geçiş çakışması özelliğini true olarak ayarlayın:

<resources>
    <style name="MyTheme">
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>
create.xml

Temalar ve stillerle çalışma hakkında daha fazla bilgi için Stiller ve Temalar başlıklı makaleyi inceleyin.

Android TV OS için uygulama geliştirme

Jetpack, TV uygulamalarında kullanılmak üzere androidx paket kitaplıklarını içerir.

TV için Compose

Android TV OS için uygulama geliştirirken Compose'u kullanmanız önerilir. Temel Compose kitaplıklarının yanı sıra, TV için Compose kitaplıkları da özellikle büyük ekran için tasarlanmış özel bileşenler sunar:

• androidx.tv.foundation
• androidx.tv.material

Android TV'de Jetpack Compose'u kullanma başlıklı makalede, TV için Compose'u kullanarak nasıl TV uygulaması oluşturacağınızı öğrenin.

Leanback kullanıcı arayüzü araç seti

Leanback kullanıcı arayüzü araç seti, TV cihazları için API'ler ve kullanıcı arayüzü widget'ları sağlar:

• androidx.leanback.app
• androidx.leanback.database
• androidx.leanback.graphics
• androidx.leanback.media
• androidx.leanback.preference
• androidx.leanback.system
• androidx.leanback.widget
• androidx.leanback.widget.picker

TV'de oynatma uygulamaları geliştirme başlıklı makalede, Leanback kullanıcı arayüzü araç setini kullanarak nasıl TV uygulaması oluşturacağınızı öğrenebilirsiniz.

TV uygulamalarını çalıştırma

Uygulamanızı çalıştırmak, geliştirme sürecinin önemli bir parçasıdır. Uygulamanızı, USB üzerinden hata ayıklamayı destekleyecek şekilde yapılandırılmış TV cihazlarında veya sanal TV cihazlarında çalıştırabilirsiniz.

Fiziksel bir cihazda çalıştırma

TV cihazınızı aşağıdaki gibi ayarlayın:

1. TV cihazınızı geliştirme makinenize bağlamak için USB kablosu kullanın. Gerekirse cihaz üreticinizin sağladığı belgelere bakın.
2. TV cihazınızda Ayarlar'a gidin.
3. Cihaz satırında Hakkında'yı seçin.
4. Derleme'ye gidin ve "Artık bir geliştiricisiniz!" mesajını alana kadar Derleme'yi birkaç kez seçin.
5. Ayarlar'a geri dönün Tercihler satırında Geliştirici seçenekleri'ni belirleyin.
6. Hata ayıklama > USB üzerinden hata ayıklama'yı ve Açık'ı seçin.
7. TV ana ekranına geri dönün.

Uygulamanızı TV cihazınızda test etmek için:

1. Android Studio'da projenizi seçin ve araç çubuğundan Çalıştır'ı tıklayın.
2. Select Deployment Target (Dağıtım Hedefini Seç) penceresinde: TV cihazınızı seçin ve OK'u (Tamam) tıklayın.

Sanal cihazda çalıştırma

Android SDK'sındaki AVD Yöneticisi, uygulamalarınızı çalıştırmak ve test etmek için sanal TV cihazları oluşturmanıza olanak tanıyan cihaz tanımları sağlar.

Sanal TV cihazı oluşturmak için:

1. AVD Yöneticisi'ni başlatın. Daha fazla bilgi için Sanal cihaz oluşturma ve yönetme başlıklı makaleyi inceleyin.
2. AVD Yöneticisi iletişim kutusunda Device Definitions (Cihaz Tanımları) sekmesini tıklayın.
3. Android TV cihaz tanımlarından birini seçip AVD oluştur'u tıklayın.
4. Emülatör seçeneklerini belirleyin ve AVD'yi oluşturmak için Tamam'ı tıklayın.

   Not: TV emülatör cihazının en iyi performansı için x86 emülatörünü kullanın ve Ana makine GPU'sunu kullan seçeneğini etkinleştirin. Kullanılabildiğinde sanal cihaz hızlandırmayı da kullanın. Emülatörün donanım hızlandırması hakkında daha fazla bilgi için Android Emülatör'de donanım hızlandırmayı yapılandırma başlıklı makaleyi inceleyin.

Uygulamanızı sanal TV cihazda test etmek için:

1. Android Studio'da projenizi seçin ve araç çubuğundan Çalıştır'ı tıklayın.
2. Select Deployment Target (Dağıtım Hedefini Seçin) penceresinde, sanal TV cihazınızı seçip OK'u (Tamam) tıklayın.

Emülatörleri kullanma hakkında daha fazla bilgi için Android Emülatör'de uygulamaları çalıştırma başlıklı makaleyi inceleyin. Android Studio'dan sanal cihazlara uygulama dağıtma hakkında daha fazla bilgi için Uygulamanızda hata ayıklama konusuna bakın.

TV uygulamanızın hazır sürüm deneyimi olarak çalışmasını sağlama

Hazır sürüm deneyimleri, kullanıcıların TV uygulamanızı yüklemeden denemesine olanak tanır ve uygulamanın benimsenme oranını artırmaya yardımcı olabilir.

TV uygulamanızı Android TV cihazında veya emülatörde hazır uygulama olarak çalışacak şekilde ayarlamak için öncelikle hazır sürüm etkin bir uygulama paketi oluşturma talimatlarını uygulayın.

Ardından, TV uygulamanızın intent-filter bölümünde MainActivity, hem LAUNCHER hem de LEANBACK_LAUNCHER öğelerinin AndroidManifest.xml içinde beyan edildiğinden emin olun:

<activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
  </activity>

TV uygulamanız artık hazır sürüm deneyimi olarak çalışacak şekilde yapılandırıldı.

TV uygulamanızı yayınlamaya hazırlama

TV uygulamanızı yayınlamaya ve dağıtmaya hazırlamak için sonraki adımları öğrenmek üzere TV uygulamaları yapılacaklar listesini inceleyin.