Tworzenie i uruchamianie aplikacji TV

Aplikacje na telewizory mają taką samą strukturę jak aplikacje na telefony i tablety. Dzięki temu możesz modyfikować dotychczasowe aplikacje, aby działały też na telewizorach, lub tworzyć nowe aplikacje na podstawie wiedzy o tworzeniu aplikacji na Androida.

Ważne: aby aplikacja kwalifikowała się jako aplikacja na Androida TV w Google Play, musi spełniać określone wymagania. Więcej informacji znajdziesz w wymaganiach dotyczących jakości aplikacji TV w aplikacji TV.

Z tego przewodnika dowiesz się, jak przygotować środowisko programistyczne do tworzenia aplikacji na telewizory oraz jakie minimalne zmiany są wymagane, aby aplikacja działała na telewizorach.

Informacje o projektowaniu aplikacji na telewizory znajdziesz w artykule Design for TV. Zapoznaj się też z przykładowymi aplikacjami w repozytorium Android TV na GitHubie.

Określanie obsługi formatów 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 na telewizor

W tej sekcji opisujemy, jak skonfigurować projekt na telewizor, niezależnie od tego, czy modyfikujesz istniejącą aplikację na Androida, aby działała na telewizorach, czy tworzysz nową aplikację TV. Jeśli masz już aplikację na Androida, dodanie obsługi Androida TV pozwoli Ci zaprojektować interfejs użytkownika na telewizor, zachowując dotychczasową architekturę aplikacji.

Uwaga: zalecamy, aby aplikacja obsługiwała zarówno urządzenia mobilne, jak i telewizory. Jeśli potrzebujesz osobnych aplikacji na urządzenia mobilne i telewizory urządzenia, możesz opublikować kilka aplikacji w tej samej ofercie 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, która działa na telewizorach, używasz 2 głównych komponentów:

• Aktywność na telewizorze: w pliku manifestu aplikacji, zadeklaruj aktywność, która ma działać na telewizorach.
• Biblioteki na telewizor: opcjonalnie możesz dołączyć jedną lub więcej bibliotek androidx dostępnych na telewizory, 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 pakietu SDK do wersji 24.0.0 lub nowszej.
  Zaktualizowane narzędzia pakietu SDK umożliwiają tworzenie i testowanie aplikacji na telewizory.
• Zaktualizuj pakiet SDK do Androida 5.0 (API 21) lub nowszego.
  Zaktualizowana wersja platformy zawiera nowe interfejsy API dla aplikacji na telewizory.
• Utwórz lub zaktualizuj projekt aplikacji.
  Aby uzyskać dostęp do nowych interfejsów API dla telewizorów, utwórz projekt lub zmodyfikuj istniejący projekt, który jest kierowany na Androida 5.0 (poziom API 21) lub nowszy.

Deklarowanie aktywności na telewizorze

Aplikacja, która ma działać na telewizorach, musi zadeklarować w pliku manifestu aktywność programu uruchamiającego na telewizor. W tym celu używa filtra intencji CATEGORY_LEANBACK_LAUNCHER. Ten filtr identyfikuje aplikację jako obsługującą telewizory i umożliwia Google Play rozpoznanie jej jako aplikacji TV. Gdy użytkownik wybierze aplikację na ekranie głównym telewizora, ta intencja określi, którą aktywność uruchomić.

Ten fragment kodu pokazuje, jak dodać ten filtr intencji do 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 manifestu aktywności w tym przykładzie określa, że jest to aktywność, która ma zostać uruchomiona na telewizorze.

Uwaga: jeśli nie dodasz do aplikacji filtra intencji CATEGORY_LEANBACK_LAUNCHER nie będzie ona widoczna dla użytkowników korzystających z Google Play na telewizorach. Jeśli aplikacja nie ma tego filtra, gdy używasz narzędzi dla deweloperów do wczytywania jej na telewizor, nie będzie się ona wyświetlać w interfejsie użytkownika telewizora.

Interfejs użytkownika aplikacji na telewizor lub część aplikacji na telewizor 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 telewizorów

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

Jeśli 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 operacyjnym Android TV.

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

Deklarowanie, że ekran dotykowy nie jest wymagany

Aplikacje, które mają działać na telewizorach, nie korzystają z ekranów dotykowych do wprowadzania danych. Aby to wyraźnie zaznaczyć, plik manifestu aplikacji na telewizor musi deklarować, że funkcja android.hardware.touchscreen nie jest wymagana. To ustawienie identyfikuje aplikację jako działającą na telewizorze i jest wymagane, aby aplikacja była uznawana za aplikację TV w Google Play. Ten przykład kodu pokazuje, jak dodać tę deklarację do 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ładzie kodu. W przeciwnym razie aplikacja nie będzie się wyświetlać w Google Play na telewizorach.

Podawanie ikony i banera na ekranie głównym

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

Aby dodać te elementy 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 na ekranie głównym

Aplikacje na Androida TV, podobnie jak wszystkie aplikacje na Androida, muszą zawierać ikonę na ekranie głównym. Sprawdzone metody projektowania punktu uruchamiania aplikacji i szczegółowe wymagania dotyczące zasobó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 w obrazie. Jeśli aplikacja jest dostępna w więcej niż 1 języku, musisz podać osobne wersje banera z tekstem w każdym obsługiwanym języku.

Zmienianie koloru programu uruchamiającego

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

Gdy uruchamia się aplikacja TV, system wyświetla animację przypominającą rozszerzające się, wypełnione koło. Aby dostosować kolor tej animacji, ustaw atrybut android:colorPrimary aplikacji TV lub aktywności na konkretny kolor. Ustaw też 2 atrybuty nakładania się przejść na 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 system operacyjny Android TV

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

Compose na TV

Compose to zalecany sposób tworzenia aplikacji na system operacyjny Android TV. Oprócz podstawowych bibliotek Compose biblioteki Compose na TV zawierają komponenty przeznaczone specjalnie na duże ekrany:

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

Dowiedz się, jak utworzyć aplikację TV za pomocą Compose na TV, w artykule Używanie Jetpack Compose na Androidzie TV.

Zestaw narzędzi interfejsu Leanback

Zestaw narzędzi interfejsu Leanback zawiera interfejsy API i widżety interfejsu użytkownika na telewizory:

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

Uruchamianie aplikacji na telewizor

Uruchamianie aplikacji jest ważnym etapem procesu tworzenia. Aplikację możesz uruchomić na telewizorach skonfigurowanych do obsługi debugowania USB lub użyć wirtualnych telewizorów.

Uruchamianie na urządzeniu fizycznym

Skonfiguruj telewizor w ten sposób:

1. Podłącz telewizor 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 Kompilacja i kliknij Kompilacja kilka razy, aż pojawi się komunikat "Jesteś teraz programistą"
5. Wróć do Ustawień. W wierszu Preferencje wybierz Opcje programisty.
6. Wybierz Debugowanie > Debugowanie przez 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 paskach narzędzi kliknij Uruchom .
2. W oknie Wybierz docelowe urządzenie wybierz telewizor i kliknij OK.

Uruchamianie na urządzeniu wirtualnym

Narzędzie AVD Manager w pakiecie Android SDK zawiera definicje urządzeń, które umożliwiają tworzenie wirtualnych telewizorów do uruchamiania i testowania aplikacji.

Aby utworzyć wirtualny telewizor:

1. Uruchom narzędzie AVD Manager. Więcej informacji znajdziesz w artykule Tworzenie urządzeń wirtualnych i zarządzanie nimi.
2. W oknie narzędzia 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 uzyskać najlepszą wydajność emulatora telewizora, użyj emulatora x86 i włącz opcję Użyj GPU hosta. Gdy jest dostępna, używaj też akceleracji urządzenia wirtualnego. Więcej informacji o akceleracji sprzętowej emulatora znajdziesz w artykule Konfigurowanie akceleracji sprzętowej na potrzeby emulatora Androida.

Aby przetestować aplikację na wirtualnym telewizorze:

1. W Androidzie Studio wybierz projekt i na paskach narzędzi kliknij Uruchom .
2. W oknie Wybierz docelowe urządzenie wybierz wirtualny telewizor 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 Androida 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 pozwalają użytkownikom wypróbować aplikację TV bez jej instalowania, co może zwiększyć liczbę instalacji.

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, aby utworzyć pakiet aplikacji z obsługą wersji błyskawicznej.

Następnie w intent-filter dla MainActivity aplikacji na telewizor upewnij się, że w pliku 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

Aby przygotować aplikację TV do publikacji i dystrybucji, zapoznaj się z listą kontrolną aplikacji TV w celu poznania kolejnych kroków.