Pierwsze kroki z aplikacjami 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.

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 telewizory znajdziesz w artykule Projektowanie aplikacji na telewizor. Więcej informacji o minimalnych wymaganiach dotyczących implementacji układów interfejsu na telewizory znajdziesz w artykule Tworzenie układów reklam na telewizory.

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

W Androidzie TV można używać większości bibliotek AndroidaX. Używaj komponentów architektury, takich jak ViewModel, aby zarządzać danymi interfejsu uwzględniającymi cykl życia, lub Room, aby integrować się z lokalnymi bazami danych SQLite tak samo jak w przypadku urządzeń mobilnych.

Większość bibliotek AndroidaX obsługuje Androida TV. Aplikacje na telewizory mogą korzystać z tej samej architektury co aplikacje mobilne. Możesz nawet współdzielić komponenty między różnymi formatami. Wystarczy, że dostosujesz sposób wyświetlania do Twojej aplikacji telewizyjnej.

Utwórz na telewizorze

Utwórz interfejs systemu operacyjnego telewizora za pomocą Jetpack Compose. Compose to nowoczesna wersja Androida do programowania UI. Oprócz podstawowych bibliotek tworzenia wiadomości wersja Compose for TV zawiera specjalne komponenty zaprojektowane specjalnie z myślą o dużym ekranie:

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

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

Zestaw narzędzi interfejsu Leanback (odradzamy)

Zestaw narzędzi interfejsu Leanback wcześniej dostarczał interfejsy API i widżety interfejsu wyłącznie na urządzenia telewizyjne wykorzystujące widoki i fragmenty Androida:

• 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 sekcji Korzystanie z zestawu narzędzi interfejsu Leanback.

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.