Pierwsze kroki z aplikacjami TV

Aplikacje na telewizory mają tę samą strukturę co aplikacje na telefony i tablety. To podobieństwo oznacza, że możesz modyfikować istniejące aplikacje, aby działały również na telewizorach, lub tworzyć nowe aplikacje na podstawie swojej wiedzy o tworzeniu aplikacji na Androida.

Ważne: aby aplikacja mogła być wyświetlana w Google Play jako aplikacja na Androida TV, musi spełniać określone wymagania. Więcej informacji znajdziesz w wymaganiach wymienionych w artykule Jakość aplikacji na telewizory.

Z tego przewodnika dowiesz się, jak przygotować środowisko programistyczne do tworzenia aplikacji na telewizory. Znajdziesz tu też informacje o minimalnych zmianach wymaganych do działania aplikacji na takich telewizorach.

Informacje na temat projektowania aplikacji na telewizory znajdziesz w artykule Projektowanie na telewizory. Przykładowe aplikacje znajdziesz w repozytorium Android TV na GitHubie.

Określanie obsługi formatów multimediów

Informacje na temat kodeków, protokołów i formatów obsługiwanych przez Androida TV znajdziesz w tej dokumentacji:

• Obsługiwane formaty multimediów
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

Konfigurowanie projektu telewizyjnego

W tej sekcji omawiamy, jak skonfigurować projekt telewizyjny, np. modyfikując istniejącą aplikację na Androida, aby uruchomił ją na urządzeniach telewizyjnych, czy tworzysz nową aplikację na Androida. Jeśli masz już aplikację na Androida, dodanie obsługi Androida TV pozwoli Ci zaprojektować interfejs użytkownika na telewizory, a jednocześnie wykorzystać istniejącą architekturę aplikacji.

Uwaga: zalecamy, aby używać jednej aplikacji, która obsługuje zarówno urządzenia mobilne, jak i telewizory. Jeśli potrzebujesz osobnych aplikacji na urządzenia mobilne i telewizory, możesz opublikować wiele aplikacji w ramach tej samej strony w Google Play, korzystając z obsługi wielu plików APK. Więcej informacji znajdziesz w artykule Obsługa wielu plików APK.

Podczas tworzenia aplikacji uruchamianej na telewizory wykorzystuje się 2 główne komponenty:

• Aktywność na telewizorach: w pliku manifestu aplikacji zadeklaruj działanie, które ma być wykonywane na urządzeniach telewizyjnych.
• Biblioteki TV: opcjonalnie możesz dodać jedną lub więcej bibliotek Androidx dostępnych na telewizory. Są one wymienione w innej sekcji tego przewodnika. Biblioteki te zawierają widżety umożliwiające tworzenie interfejsów użytkownika.

Wymagania wstępne

Zanim rozpoczniesz tworzenie aplikacji na telewizory, musisz wykonać te czynności:

• Zaktualizuj narzędzia pakietu SDK do wersji 24.0.0 lub nowszej.
  Zaktualizowane narzędzia SDK umożliwiają tworzenie i testowanie aplikacji na telewizory.
• Zaktualizuj pakiet SDK do Androida 5.0 (API 21) lub nowszego.
  Zaktualizowana wersja platformy udostępnia nowe interfejsy API dla aplikacji telewizyjnych.
• Utwórz lub zaktualizuj projekt aplikacji.
  Aby uzyskać dostęp do nowych interfejsów API dla urządzeń telewizyjnych, utwórz projekt lub zmodyfikuj istniejący projekt kierowany na Androida 5.0 (poziom API 21) lub nowszego.

Deklarowanie aktywności związanej z telewizją

Aplikacja przeznaczona do działania na telewizorach musi zadeklarować w pliku manifestu aktywność programu uruchamiającego dla telewizora. Używa do tego filtra intencji CATEGORY_LEANBACK_LAUNCHER. Ten filtr identyfikuje aplikację jako obsługującą telewizor i pozwala Google Play zidentyfikować ją jako aplikację na telewizory. Gdy użytkownik wybierze aplikację na ekranie głównym telewizora, ta intencja określa, którą aktywność należy uruchomić.

Ten fragment kodu pokazuje, jak uwzględnić filtr intencji w pliku manifestu:

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

Drugi wpis w pliku manifestu aktywności w tym przykładzie określa, że jest to działanie do uruchomienia na telewizorze.

Uwaga: jeśli nie zastosujesz w aplikacji filtra intencji CATEGORY_LEANBACK_LAUNCHER, nie będzie on widoczny dla użytkowników korzystających z Google Play na telewizorach. Jeśli aplikacja nie ma tego filtra podczas wczytywania jej na telewizorze za pomocą narzędzi dla programistów, nie pojawi się ona w interfejsie telewizora.

Interfejs użytkownika aplikacji TV lub jej część na telewizory musi zapewniać prosty interfejs ułatwiający nawigację przy użyciu pilota z odległości 3 metrów. Jeśli modyfikujesz istniejącą aplikację na telewizory, nie używaj tego samego układu aktywności w przypadku telewizora, którego używasz na telefonie i tablecie. Wskazówki dotyczące projektowania aplikacji na telewizory znajdziesz w artykule Projektowanie na telewizory. Więcej informacji o minimalnych wymaganiach związanych z implementacją układów interfejsu na telewizorze znajdziesz w artykule Tworzenie układów dla telewizora.

Deklarowanie obsługi telewizora

Zadeklaruj, że aplikacja jest przeznaczona na Androida TV, deklarując funkcję android.software.leanback.

Jeśli Twoja aplikacja działa zarówno na urządzeniach mobilnych, jak i na telewizorach, ustaw wartość atrybutu required na false. Jeśli ustawisz wartość atrybutu required na true, Google Play udostępni Twoją aplikację tylko na Androidzie TV.

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

Zadeklaruj, że ekran dotykowy nie jest wymagany

Aplikacje przeznaczone do działania na telewizorach nie wymagają wprowadzania danych na ekranach dotykowych. Aby było to jasne, plik manifestu aplikacji na telewizor musi deklarować, że funkcja android.hardware.touchscreen nie jest wymagana. To ustawienie określa, że aplikacja może działać na urządzeniu TV i jest wymagane, aby została uznana za aplikację telewizyjną w Google Play. Z poniższego przykładu kodu dowiesz się, jak dołączyć tę deklarację z pliku manifestu:

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

Uwaga: w pliku manifestu aplikacji musisz zadeklarować, że ekran dotykowy nie jest wymagany, zgodnie z tym przykładowym kodem. W przeciwnym razie aplikacja nie jest widoczna w Google Play na telewizorach.

Dodaj ikonę i baner na ekranie głównym

Aplikacje na Androida TV muszą mieć w każdej lokalizacji zarówno ikonę ekranu głównego, jak i obraz banera. W zależności od urządzenia z Androidem TV jako punkt uruchamiania aplikacji pojawia się ikona lub baner wyświetlany na ekranie głównym w wierszach aplikacji i gier.

Aby dodać je do aplikacji, opisz ikonę i baner w pliku manifestu w ten sposób:

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

Ikona ekranu głównego

Aplikacje na Androida TV, podobnie jak wszystkie aplikacje na Androida, muszą mieć ikonę na ekranie głównym. Sprawdzone metody projektowania najlepszego momentu wprowadzenia aplikacji na rynek oraz szczegółowe wymagania dotyczące zasobów znajdziesz w wytycznych dotyczących ikony aplikacji na Androida TV i banerów.

Baner na ekranie głównym

Użyj atrybutu android:banner z tagiem <application>, aby podać domyślny baner dla wszystkich działań w aplikacji lub tag <activity>, aby wygenerować baner dotyczący określonej aktywności.

Do banera użyj zasobu xhdpi o wymiarach 320 x 180 pikseli. Obraz musi zawierać tekst. Jeśli Twoja aplikacja jest dostępna w więcej niż 1 języku, musisz przesłać osobne wersje banera z tekstem dla każdego obsługiwanego języka.

Zmienianie koloru Menu z aplikacjami

Uwaga: w Androidzie 12 i nowszych niestandardowe animacje ekranu powitalnego utworzone za pomocą interfejsu API platformy SplashScreen nie są obsługiwane w przypadku aplikacji na Androida TV.

Po uruchomieniu aplikacji TV system wyświetla animację przypominającą rozwijane, wypełnione kółko. Aby dostosować kolor tej animacji, wybierz konkretny kolor atrybutu android:colorPrimary aplikacji lub aktywności na telewizorze. Ustaw też 2 atrybuty pokrywania się przejść na true, jak w tym fragmencie kodu z pliku XML zasobów motywu:

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

Więcej informacji o pracy z motywami i stylami znajdziesz w artykule Style i motywy.

Tworzenie aplikacji na system operacyjny Android TV

Jetpack zawiera biblioteki pakietów androidx do wykorzystania z aplikacjami na telewizory.

Utwórz na telewizorze

Tworzenie wiadomości to zalecany sposób tworzenia aplikacji na system operacyjny Android TV. Oprócz podstawowych bibliotek Compose for TV biblioteki Compose for TV zawierają dedykowane komponenty zaprojektowane specjalnie pod kątem dużego ekranu:

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

Aby dowiedzieć się, jak utworzyć aplikację na telewizor przy użyciu funkcji Utwórz w TV, zapoznaj się z artykułem Korzystanie z Jetpack Compose na urządzeniu z Androidem TV.

Zestaw narzędzi interfejsu TalkBack

Zestaw narzędzi interfejsu Suica zawiera interfejsy API i widżety interfejsu dla urządzeń telewizyjnych:

• 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

Dowiedz się, jak utworzyć aplikację na telewizor przy użyciu zestawu narzędzi interfejsu TalkBack z artykułu Tworzenie aplikacji do odtwarzania w telewizji.

Uruchamianie aplikacji TV

Uruchamianie aplikacji to ważna część procesu programowania. Możesz ją uruchamiać na telewizorach skonfigurowanych pod kątem obsługi debugowania USB lub używać urządzeń telewizyjnych wirtualnych.

Uruchamianie na urządzeniu fizycznym

Skonfiguruj telewizor w ten sposób:

1. Podłącz telewizor do komputera, używając kabla USB. W razie potrzeby zapoznaj się z dokumentacją udostępnioną przez producenta urządzenia.
2. Na telewizorze otwórz Ustawienia.
3. W wierszu Urządzenie wybierz Informacje.
4. Przewiń do sekcji Kompilacja i kilka razy kliknij Kompilacja, aż pojawi się komunikat „Jesteś teraz programistą!”.
5. Wróć do Ustawień. W wierszu Preferencje wybierz Opcje programisty.
6. Wybierz kolejno Debugowanie > Debugowanie USB i kliknij Wł.
7. Wróć do ekranu głównego telewizora.

Aby przetestować aplikację na telewizorze:

1. W Android Studio wybierz projekt i na pasku narzędzi kliknij Uruchom .
2. W oknie Select Deployment Target (Wybierz cel wdrożenia) wybierz urządzenie TV i kliknij OK.

Uruchamianie na urządzeniu wirtualnym

Menedżer AVD w pakiecie Android SDK udostępnia definicje urządzeń, które umożliwiają tworzenie wirtualnych urządzeń telewizyjnych do uruchamiania i testowania aplikacji.

Aby utworzyć wirtualny telewizor:

1. Uruchom Menedżera AVD. Więcej informacji znajdziesz w artykule o tworzeniu urządzeń wirtualnych i zarządzaniu nimi.
2. W oknie dialogowym AVD Manager kliknij kartę Definicje urządzeń.
3. Wybierz jedną z definicji urządzeń z Androidem TV i kliknij Utwórz AVD.
4. Wybierz opcje emulatora i kliknij OK, aby utworzyć AVD.

   Uwaga: aby uzyskać najlepszą wydajność emulatora TV, użyj emulatora x86 i włącz opcję Użyj hosta GPU. Używaj też akceleracji urządzeń wirtualnych, gdy jest dostępna. Więcej informacji o akceleracji sprzętowej emulatora znajdziesz w artykule o konfigurowaniu akceleracji sprzętowej emulatora Androida.

Aby przetestować aplikację na telewizorze wirtualnym:

1. W Android Studio wybierz projekt i na pasku narzędzi kliknij Uruchom .
2. W oknie Select Deployment Target (Wybierz cel wdrożenia) wybierz urządzenie TV wirtualnej i kliknij OK.

Więcej informacji o używaniu emulatorów znajdziesz w artykule Uruchamianie aplikacji przy użyciu emulatora Androida. Więcej informacji o wdrażaniu aplikacji z Android Studio na urządzeniach wirtualnych znajdziesz w artykule Debugowanie aplikacji.

Włącz aplikację TV jako aplikację błyskawiczną

Aplikacje błyskawiczne ułatwiają użytkownikom wypróbowanie aplikacji na telewizor i mogą pomóc w zwiększeniu jej rozpowszechnienia.

Aby skonfigurować uruchamianie aplikacji TV jako aplikacji błyskawicznej na urządzeniu z Androidem TV lub emulatorze, najpierw wykonaj instrukcje tworzenia pakietu aplikacji obsługującego aplikacje błyskawiczne.

Następnie w intent-filter dla elementu MainActivity aplikacji TV upewnij się, że LAUNCHER i LEANBACK_LAUNCHER są zadeklarowane w AndroidManifest.xml:

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

Aplikacja TV jest teraz skonfigurowana do uruchamiania jako aplikacji błyskawicznej.

Przygotowanie aplikacji TV do publikacji

Zapoznaj się z listą kontrolną aplikacji telewizyjnych, aby dowiedzieć się, jak przygotować aplikację do publikacji i dystrybucji.