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

TV uygulamaları, telefonlar ve tabletler için olanlarla 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 oluşturma hakkında zaten bildiklerinize dayanarak 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 bakı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.

Not: Hem mobil cihazları hem de TV cihazlarını destekleyen tek bir uygulamanız olmasını öneririz. Mobil cihazlar ve TV cihazları için ayrı uygulamalara ihtiyacınız varsa Google Play'de aynı listeleme altında birden fazla uygulama yayınlamak için çoklu APK desteğini kullanabilirsiniz. Daha fazla bilgi için Birden fazla APK desteği bölümüne bakın.

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ı işlemi beyan etmelidir. Bunu yapmak için CATEGORY_LEANBACK_LAUNCHER amaç filtresi kullanır. Bu filtre, uygulamanızın TV'de etkinleştirildiğini 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ı tanımlar.

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 manifest 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, geliştirici araçlarını kullanarak uygulamanızı TV cihazına yüklediğinizde uygulamanızda 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 mesafedeki 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 bildirme

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 özelliği değerini false olarak ayarlayın. required özelliğinin değerini true olarak ayarlarsanız Google Play, uygulamanızı yalnızca Android TV OS'te kullanılabilir hale getirir.

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

Dokunmatik ekranın gerekli olmadığını bildirme

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ığı belirtilmelidir. 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ı belirtmeniz 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, uygulamalar ve oyunlar satırlarında ana ekranda görünen 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 şekilde 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 şartları ile 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, belirli bir etkinlik için banner sağlamak üzere ise <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, bir 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ıyla kullanılmak üzere androidx paket kitaplıklarını içerir.

TV için Compose

Android TV OS için uygulama oluşturmak üzere Compose'u kullanmanızı öneririz. 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 oynatma uygulamaları oluşturma 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 seçin.
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çip 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. Ayrıca, kullanılabilir olduğunda 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 cihazında 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: Sanal TV cihazınızı seçin ve 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 başlıklı makaleyi inceleyin.

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

Hazır uygulama deneyimleri, kullanıcıların TV uygulamanızı yüklemeden denemesine olanak tanır ve uygulamanın daha fazla kullanıcı tarafından benimsenmesine 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 uygulama paketi oluşturma talimatlarını uygulayın.

Ardından, TV uygulamanızın intent-filter için MainActivity bölümünde 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 uygulama deneyimi olarak çalışacak şekilde yapılandırıldı.

TV uygulamanızı yayınlamaya hazırlama

TV uygulamanızı yayınlanmaya ve dağıtıma hazırlamak için sonraki adımları TV uygulamaları yapılacaklar listesinde inceleyin.