Tworzenie i uruchamianie aplikacji TV

Aplikacje na telewizory mają taką samą strukturę jak aplikacje na telefony i tablety. Podobieństwo to oznacza, że możesz modyfikować istniejące aplikacje, aby działały również na urządzeniach TV, lub tworzyć nowe aplikacje na podstawie tego, co już wiesz o tworzeniu aplikacji na Androida.

Ważne: aby aplikacja mogła być uznana za aplikację na Androida TV w Google Play, musi spełniać określone wymagania. Więcej informacji znajdziesz w wymaganiach wymienionych w sekcji Jakość aplikacji TV.

Z tego przewodnika dowiesz się, jak przygotować środowisko programistyczne do tworzenia aplikacji na telewizory oraz jakie minimalne zmiany są wymagane, aby umożliwić uruchomienie aplikacji na urządzeniach TV.

Informacje o projektowaniu aplikacji na telewizory znajdziesz w artykule Projektowanie aplikacji na telewizory. Zobacz też przykładowe aplikacje w repozytorium GitHub Androida TV.

Sprawdzanie obsługi formatu multimediów

Informacje o kodekach, protokołach i formatach obsługiwanych przez Androida TV znajdziesz w tych dokumentach:

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

Konfigurowanie projektu telewizyjnego

W tej sekcji omawiamy, jak skonfigurować projekt telewizyjny, niezależnie od tego, czy modyfikujesz istniejącą aplikację na Androida, aby działała na urządzeniach TV, czy tworzysz nową aplikację TV. Jeśli masz już aplikację na Androida, dodanie obsługi Androida TV umożliwi Ci zaprojektowanie interfejsu użytkownika na TV przy jednoczesnym ponownym wykorzystaniu istniejącej architektury aplikacji.

Podczas tworzenia aplikacji działającej na urządzeniach TV używasz 2 głównych komponentów:

• Aktywność na telewizorze: w pliku manifestu aplikacji zadeklaruj aktywność przeznaczoną do uruchamiania na telewizorach.
• Biblioteki TV: opcjonalnie możesz uwzględnić co najmniej jedną z bibliotek androidx dostępnych na urządzenia TV, które są wymienione w innej sekcji tego przewodnika. Biblioteki te zawierają widżety do tworzenia interfejsów użytkownika.

Wymagania wstępne

Zanim zaczniesz tworzyć aplikację na telewizor, musisz wykonać te czynności:

• Zaktualizuj narzędzia 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 na telewizory.
• Utwórz lub zaktualizuj projekt aplikacji.
  Aby uzyskać dostęp do nowych interfejsów API na urządzenia TV, utwórz projekt lub zmodyfikuj istniejący projekt, który jest kierowany na Androida 5.0 (poziom API 21) lub nowszego.

Deklarowanie aktywności w telewizji

Aplikacja przeznaczona do działania na urządzeniach z Androidem TV musi deklarować w pliku manifestu aktywność programu uruchamiającego dla Androida TV. W tym celu używa filtra CATEGORY_LEANBACK_LAUNCHER. Ten filtr określa, że aplikacja jest włączona na telewizorze, i umożliwia Google Play rozpoznanie jej jako aplikacji TV. Gdy użytkownik wybierze aplikację na ekranie głównym telewizora, ten zamiar określi, które działanie ma zostać uruchomione.

Poniższy fragment kodu pokazuje, jak uwzględnić ten filtr intencji w manifeście:

<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 aktywność, która ma zostać uruchomiona na urządzeniu TV.

Ostrzeżenie: jeśli nie uwzględnisz w aplikacji filtra intencji CATEGORY_LEANBACK_LAUNCHER, nie będzie ona widoczna dla użytkowników korzystających z Google Play na urządzeniach z Androidem TV. Jeśli podczas wczytywania aplikacji na urządzenie TV za pomocą narzędzi dla deweloperów nie ma tego filtra, aplikacja nie pojawi się w interfejsie użytkownika TV.

Interfejs aplikacji na telewizor lub część telewizyjna istniejącej aplikacji musi zapewniać intuicyjną nawigację za pomocą pilota z odległości 3 metrów. Jeśli modyfikujesz istniejącą aplikację, aby można było jej używać na telewizorze, nie używaj tego samego układu aktywności na telewizorze, co na telefonach i tabletach. Wskazówki dotyczące projektowania aplikacji na telewizory znajdziesz w artykule Projektowanie aplikacji na telewizory.

Deklarowanie obsługi urządzeń TV

Zadeklaruj, że Twoja 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 w systemie Android TV.

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

Deklarowanie, że ekran dotykowy nie jest wymagany

Aplikacje przeznaczone do uruchamiania na telewizorach nie korzystają z ekranów dotykowych do wprowadzania danych. Aby to wyjaśnić, 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. Jest ono wymagane, aby aplikacja była uznawana za aplikację TV w Google Play. Poniższy przykład kodu pokazuje, jak uwzględnić tę deklarację w 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, jak pokazano w tym przykładowym kodzie. W przeciwnym razie aplikacja nie będzie się wyświetlać w Google Play na urządzeniach z Androidem TV.

Podaj ikonę ekranu głównego i baner

Aplikacje na Androida TV muszą zawierać ikonę ekranu głównego i obraz banera w przypadku każdej wersji językowej. W zależności od urządzenia z Androidem TV jako punkt uruchamiania aplikacji na ekranie głównym w wierszach aplikacji i gier używana jest ikona lub baner.

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 dobrego punktu startowego aplikacji i szczegółowe wymagania dotyczące komponentów znajdziesz w  wytycznych dotyczących ikony i banera aplikacji na Androida TV.

Baner na ekranie głównym

Użyj atrybutu android:banner z tagiem <application> , aby podać domyślny baner dla wszystkich aktywności aplikacji, lub z tagiem <activity> , aby podać baner dla konkretnej aktywności.

W przypadku banera użyj zasobu xhdpi o rozmiarze 320 × 180 pikseli. Tekst musi być zawarty na obrazie. 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.

Zmiana koloru Menu z aplikacjami

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

Gdy aplikacja TV zostanie uruchomiona, system wyświetli animację przypominającą rozszerzający się, wypełniony okrąg. Aby dostosować kolor tej animacji, ustaw atrybut android:colorPrimary aplikacji TV lub aktywności na telewizorze na określony kolor. Ustaw też 2 atrybuty nakładania się przejść na wartość true, jak pokazano w tym fragmencie kodu z pliku XML zasobu motywu:

<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

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

Tworzenie aplikacji na Androida TV

Jetpack zawiera biblioteki pakietu androidx do używania w aplikacjach na telewizory.

Compose na TV

Compose to zalecany sposób tworzenia aplikacji na Androida TV. Oprócz podstawowych bibliotek Compose biblioteki Compose na TV udostępniają dedykowane komponenty zaprojektowane specjalnie z myślą o dużych ekranach:

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

Dowiedz się, jak tworzyć aplikacje TV za pomocą Compose na TV, w artykule Korzystanie z Jetpack Compose na Androidzie TV.

Zestaw narzędzi interfejsu Leanback

Zestaw narzędzi Leanback UI zawiera interfejsy API i widżety interfejsu użytkownika dla urządzeń TV:

• 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 tworzyć aplikacje TV za pomocą pakietu narzędzi interfejsu Leanback w artykule Tworzenie aplikacji do odtwarzania na telewizorze.

Uruchamianie aplikacji TV

Uruchamianie aplikacji to ważny etap procesu tworzenia. Aplikację możesz uruchamiać na urządzeniach TV skonfigurowanych do obsługi debugowania USB lub na wirtualnych urządzeniach TV.

Uruchamianie na urządzeniu fizycznym

Skonfiguruj telewizor w ten sposób:

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

Aby przetestować aplikację na telewizorze:

1. W Androidzie Studio wybierz projekt i na pasku narzędzi kliknij Uruchom .
2. W oknie Wybierz miejsce docelowe wdrożenia wybierz telewizor i kliknij OK.

Uruchamianie na urządzeniu wirtualnym

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

Aby utworzyć wirtualne urządzenie TV:

1. Uruchom narzędzie AVD Manager. Więcej informacji znajdziesz w artykule Tworzenie urządzeń wirtualnych i zarządzanie nimi.
2. W oknie [narzędzie] AVD Manager kliknij kartę Definicje urządzeń.
3. Wybierz jedną z definicji urządzenia z Androidem TV i kliknij Utwórz AVD.
4. Wybierz opcje emulatora i kliknij OK, aby utworzyć AVD.

   Uwaga: aby emulator urządzenia telewizyjnego działał jak najlepiej, użyj emulatora x86 i włącz opcję Użyj procesora GPU hosta. Używaj też akceleracji urządzenia wirtualnego, gdy jest dostępna. Więcej informacji o akceleracji sprzętowej w emulatorze znajdziesz w artykule Konfigurowanie akceleracji sprzętowej w Android Emulatorze.

Aby przetestować aplikację na wirtualnym telewizorze:

1. W Androidzie Studio wybierz projekt i na pasku narzędzi kliknij Uruchom .
2. W oknie Wybierz miejsce wdrożenia wybierz wirtualne urządzenie TV i kliknij OK.

Więcej informacji o korzystaniu z emulatorów znajdziesz w artykule Uruchamianie aplikacji w emulatorze Androida. Więcej informacji o wdrażaniu aplikacji z Android Studio na urządzenia wirtualne znajdziesz w artykule Debugowanie aplikacji.

Włączanie możliwości uruchamiania aplikacji TV jako aplikacji błyskawicznej

Aplikacje błyskawiczne umożliwiają użytkownikom wypróbowanie aplikacji TV bez jej instalowania, co może zwiększyć liczbę jej użytkowników.

Aby skonfigurować aplikację TV, tak aby działała jako aplikacja błyskawiczna na urządzeniu z Androidem TV lub emulatorze, najpierw postępuj zgodnie z instrukcjami tworzenia pakietu aplikacji z obsługą wersji błyskawicznej.

Następnie w intent-filter dla MainActivity aplikacji na telewizory upewnij się, że w AndroidManifest.xml zadeklarowano zarówno LAUNCHER, jak i LEANBACK_LAUNCHER:

<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 działania jako aplikacja błyskawiczna.

Przygotowywanie aplikacji TV do publikacji

Zapoznaj się z listą kontrolną aplikacji TV, aby poznać kolejne kroki przygotowania aplikacji TV do publikacji i dystrybucji.