Tworzenie i uruchamianie aplikacji TV

Aplikacje na telewizory mają taką samą strukturę jak aplikacje na telefony i tablety. Oznacza to, że możesz modyfikować istniejące aplikacje, aby działały też na telewizorach, lub tworzyć nowe na podstawie tego, co już wiesz o tworzeniu aplikacji na Androida.

Ważne: aby aplikacja mogła zostać 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 na telewizory.

Z tego przewodnika dowiesz się, jak przygotować środowisko programistyczne do tworzenia aplikacji telewizyjnych i jakie są minimalne wymagane zmiany, które pozwolą na uruchomienie aplikacji na urządzeniach telewizyjnych.

Więcej informacji o projektowaniu aplikacji na telewizor znajdziesz w artykule Projektowanie aplikacji na telewizor. Zobacz też przykładowe aplikacje w repozytorium Androida TV na GitHubie.

Określ obsługiwane formaty multimediów

W poniższej dokumentacji znajdziesz informacje o kodekach, protokołach i formatach obsługiwanych przez Androida TV:

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

Konfigurowanie projektu telewizyjnego

W tej sekcji omawiamy, jak skonfigurować projekt na telewizory – niezależnie od tego, czy modyfikujesz istniejącą aplikację na Androida, aby działała na telewizorach, czy tworzysz nową. Jeśli masz już aplikację na Androida, dodanie obsługi Androida TV pozwoli Ci zaprojektować interfejs TV z wykorzystaniem istniejącej architektury aplikacji.

Uwaga: zalecamy, aby mieć jedną aplikację, 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 aplikacji w Google Play, korzystając z obsługi wielu plików APK. Więcej informacji znajdziesz w artykule o obsłudze wielu plików APK.

Istnieją 2 główne komponenty, które wykorzystujesz do tworzenia aplikacji działających na telewizorach:

• Aktywność dla telewizora: w pliku manifestu aplikacji zadeklaruj działanie, które ma być uruchamiane na urządzeniach telewizyjnych.
• Biblioteki TV: opcjonalnie dołącz co najmniej 1 z bibliotek Androidax dostępnych na potrzeby urządzeń telewizyjnych (wymienionych w innej sekcji tego przewodnika). Te biblioteki udostępniają widżety do tworzenia interfejsów użytkownika.

Wymagania wstępne

Przed rozpoczęciem tworzenia aplikacji na telewizory musisz wykonać następujące czynności:

• Zaktualizuj pakiet SDK do wersji 24.0.0 lub nowszej.
  Zaktualizowane narzędzia SDK pozwalają tworzyć i testować aplikacje na telewizory.
• Zaktualizuj pakiet SDK do Androida w wersji 5.0 (API 21) lub nowszej.
  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 interfejsu API 21) lub nowszego.

Deklarowanie aktywności telewizyjnej

Aplikacja, która ma działać na urządzeniach telewizyjnych, musi w pliku manifestu zadeklarować aktywność programu uruchamiającego dla telewizora. Do tego celu wykorzystuje filtr intencji CATEGORY_LEANBACK_LAUNCHER. Ten filtr identyfikuje aplikację jako dostępną na telewizorze i pozwala Google Play zidentyfikować ją jako aplikację na telewizory. Gdy użytkownik wybierze Twoją aplikację na ekranie głównym telewizora, intencja określa, jakie działanie należy uruchomić.

Ten fragment kodu pokazuje, jak uwzględnić ten 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>

Druga pozycja w pliku manifestu aktywności w tym przykładzie określa, że jest to działanie, które ma zostać uruchomione na telewizorze.

Uwaga: jeśli w swojej aplikacji nie dodasz filtra intencji CATEGORY_LEANBACK_LAUNCHER, nie będzie on widoczny dla użytkowników korzystających z Google Play na telewizorach. Poza tym, jeśli Twoja aplikacja nie ma tego filtra podczas wczytywania na telewizorze narzędzi dla programistów, nie będzie ona widoczna w interfejsie telewizora.

Interfejs aplikacji TV lub jej część na telewizory musi zapewniać prosty interfejs umożliwiający łatwą nawigację przy użyciu pilota z odległości 3 metrów. Jeśli modyfikujesz istniejącą aplikację na potrzeby telewizora, nie używaj tego samego układu aktywności na telewizorze, z którego korzystasz na telefonach i tabletach. Wskazówki projektowania aplikacji na telewizor znajdziesz w artykule Projektowanie aplikacji na telewizor.

Zadeklaruj, że telewizor jest obsługiwany

Zadeklaruj, że Twoja aplikacja jest przeznaczona na Androida TV, zadeklarują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 aplikację tylko na urządzeniach z Androidem TV.

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

Deklarowanie ekranu dotykowego nie jest wymagane

Aplikacje do działania na telewizorach nie wykorzystują ekranów dotykowych do wprowadzania danych. Aby było to jasne, musisz w pliku manifestu aplikacji TV zadeklarować, że funkcja android.hardware.touchscreen nie jest wymagana. To ustawienie określa, że Twoja aplikacja może działać na telewizorze, i jest wymagane, aby została uznana za aplikację telewizyjną w Google Play. Poniższy przykładowy kod 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 pojawi się w Google Play na telewizorach.

Dodaj ikonę i baner na ekran główny

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

Aby dodać je do swojej 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, tak jak wszystkie aplikacje na Androida, muszą zawierać ikonę na ekranie głównym. Sprawdzone metody wyznaczania optymalnego momentu wprowadzenia aplikacji na rynek oraz szczegółowe wymagania dotyczące zasobów znajdziesz w wytycznych dotyczących ikon i banerów aplikacji na Androida TV.

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 za pomocą tagu <activity>, aby dodać baner dla konkretnej aktywności.

W przypadku banera użyj zasobu xhdpi o rozmiarze 320 x 180 pikseli. Obraz musi zawierać tekst. Jeśli Twoja aplikacja jest dostępna w kilku językach, musisz dla każdego obsługiwanego języka dostarczyć osobne wersje banera z tekstem.

Zmienianie koloru programu uruchamiającego

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

Po uruchomieniu aplikacji TV system wyświetla animację, która przypomina rozwijany, wypełniony okrąg. Aby dostosować kolor tej animacji, ustaw konkretny kolor w atrybucie android:colorPrimary aplikacji TV lub aktywności. Ustaw też 2 atrybuty nakładania się przejść na true zgodnie z poniższym fragmentem kodu z pliku XML zasobu 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 użytku z aplikacjami na telewizory.

Utwórz na telewizorze

Tworzenie to zalecany sposób tworzenia aplikacji na system operacyjny Android TV. Oprócz podstawowych bibliotek Compose znajdziesz biblioteki w usłudze Compose for TV, które zawierają specjalne komponenty zaprojektowane specjalnie pod kątem dużego ekranu:

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

Aby dowiedzieć się, jak utworzyć aplikację TV za pomocą funkcji Compose for TV, przeczytaj artykuł Korzystanie z Jetpack Compose na Androidzie TV.

Zestaw narzędzi interfejsu Leanback

Zestaw narzędzi interfejsu Leanback zawiera interfejsy API i widżety interfejsu dla telewizorów:

• 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 przy użyciu zestawu narzędzi interfejsu Leanback w artykule o tworzeniu aplikacji do odtwarzania telewizji.

Uruchamianie aplikacji TV

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

Uruchom na urządzeniu fizycznym

Skonfiguruj telewizor w ten sposób:

1. Podłącz telewizor do komputera 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 Kompilacji i kliknij kilka razy Build, aż pojawi się komunikat „Jesteś teraz programistą”.
5. Wróć do Ustawień. W wierszu Ustawienia wybierz 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 Android Studio wybierz projekt i kliknij Uruchom na pasku narzędzi.
2. W oknie Wybierz cel wdrożenia wybierz urządzenie TV i kliknij OK.

Uruchamianie na urządzeniu wirtualnym

AVD Manager w pakiecie Android SDK udostępnia definicje urządzeń, które pozwalają tworzyć wirtualne urządzenia telewizyjne do uruchamiania i testowania aplikacji.

Aby utworzyć telewizor wirtualny:

1. Uruchom program AVD Manager. Więcej informacji znajdziesz w artykule o tworzeniu urządzeń wirtualnych i zarządzaniu nimi.
2. W oknie dialogowym AVD Manager kliknij kartę Device Definitions (Definicje urządzeń).
3. Wybierz jedną z definicji urządzeń z Androidem TV i kliknij Utwórz średni czas oglądania.
4. Wybierz opcje emulatora i kliknij OK, aby utworzyć AVD.

   Uwaga: aby uzyskać najlepszą wydajność urządzenia emulatora TV, użyj emulatora x86 i włącz opcję Użyj GPU hosta. Możesz też używać akceleracji urządzenia wirtualnego, jeśli 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 wirtualnej:

1. W Android Studio wybierz projekt i kliknij Uruchom na pasku narzędzi.
2. W oknie Wybierz cel wdrożenia wybierz urządzenie wirtualnej telewizji i kliknij OK.

Więcej informacji o korzystaniu z emulatorów znajdziesz w artykule Uruchamianie aplikacji za pomocą emulatora Androida. Więcej informacji o wdrażaniu aplikacji z Android Studio na urządzeniach wirtualnych znajdziesz w artykule Debugowanie aplikacji.

Włącz uruchamianie aplikacji TV jako aplikacji błyskawicznej

Funkcje błyskawiczne ułatwiają użytkownikom wypróbowanie aplikacji na telewizory i mogą zwiększyć jej rozpowszechnienie.

Aby skonfigurować aplikację TV do uruchamiania jako aplikacji błyskawicznej na urządzeniu z Androidem TV lub w emulatorze, najpierw wykonaj instrukcje tworzenia pakietu aplikacji obsługującej aplikacje błyskawiczne.

Następnie w polu intent-filter właściwości MainActivity aplikacji TV upewnij się, że w polu 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>

Twoja aplikacja na telewizory jest teraz skonfigurowana do uruchamiania aplikacji błyskawicznej.

Przygotowywanie aplikacji na telewizory do publikacji

Zapoznaj się z listą kontrolną aplikacji telewizyjnych, aby poznać następne kroki, które pomogą Ci przygotować aplikację na telewizory do publikacji i dystrybucji.