TV apps use the same structure as those for phones and tablets. This similarity means you can modify your existing apps to also run on TV devices or create new apps based on what you already know about building apps for Android.
Important: There are specific requirements your app must meet to qualify as an Android TV app on Google Play. For more information, see the requirements listed in TV App Quality.
This lesson describes how to prepare your development environment for building TV apps, and the minimum required changes to enable an app to run on TV devices.
See the following documentation for information about the codecs, protocols, and formats supported by Android TV.
android.drmThis section discusses how to modify an existing app to run on TV devices, or create a new one. These are the main components you must use to create an app that runs on TV devices:
Before you begin building apps for TV, you must:
An application intended to run on TV devices must declare a launcher activity for TV in its manifest using a {@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent filter. This filter identifies your app as being enabled for TV, and is required for your app to be considered a TV app in Google Play. Declaring this intent also identifies which activity in your app to launch when a user selects its icon on the TV home screen.
The following code snippet shows how to include this intent filter in your manifest:
<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>
The second activity manifest entry in this example specifies that activity as the one to launch on a TV device.
Caution: If you do not include the {@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent filter in your app, it is not visible to users running the Google Play store on TV devices. Also, if your app does not have this filter when you load it onto a TV device using developer tools, the app does not appear in the TV user interface.
If you are modifying an existing app for use on TV, your app should not use the same activity layout for TV that it does for phones and tablets. The user interface of your TV app (or TV portion of your existing app) should provide a simpler interface that can be easily navigated using a remote control from a couch. For guidelines on designing an app for TV, see the TV Design guide. For more information on the minimum implementation requirements for interface layouts on TV, see Building TV Layouts.
Declare that your app uses the Leanback user interface required by Android TV. If you are developing an app that runs on mobile (phones, wearables, tablets, etc.) as well as Android TV, set the {@code required} attribute value to {@code false}. If you set the {@code required} attribute value to {@code true}, your app will run only on devices that use the Leanback UI.
<manifest>
<uses-feature android:name="android.software.leanback"
android:required="false" />
...
</manifest>
Applications that are intended to run on TV devices do not rely on touch screens for input. In order to make this clear, the manifest of your TV app must declare that a the {@code android.hardware.touchscreen} feature is not required. This setting identifies your app as being able to work on a TV device, and is required for your app to be considered a TV app in Google Play. The following code example shows how to include this manifest declaration:
<manifest>
<uses-feature android:name="android.hardware.touchscreen"
android:required="false" />
...
</manifest>
Caution: You must declare that a touch screen is not required in your app manifest, as shown this example code, or your app cannot appear in the Google Play store on TV devices.
An application must provide a home screen banner image for each localization if it includes a Leanback launcher intent filter. The banner is the app launch point that appears on the home screen in the apps and games rows. When designing your banner, follow the design requirements described in Banners. To add the banner to your app, describe the banner in the manifest as follows:
<application
...
android:banner="@drawable/banner" >
...
</application>
Use the {@code android:banner}
attribute with the <application>
tag to supply a default banner for all application activities, or with the
<activity>
tag to supply a banner for a specific activity.
When a TV app launches, the system displays an animation that resembles an expanding, filled
circle. To customize the color of this animation, set the android:colorPrimary
attribute of your TV app or activity to a specific color. You should also set two additional
transition overlap attributes to true, as shown in the following snippet from a
theme resource XML file:
<resources>
<style ... >
<item name="android:colorPrimary">@color/primary</item>
<item name="android:windowAllowReturnTransitionOverlap">true</item>
<item name="android:windowAllowEnterTransitionOverlap">true</item>
</style>
</resources>
For more information about working with themes and styles, see Styles and Themes.
The Android SDK includes support libraries that are intended for use with TV apps. These
libraries provide APIs and user interface widgets for use on TV devices. The libraries are
located in the {@code
Note: You are not required to use these support libraries for your TV app. However, we strongly recommend using them, particularly for apps that provide a media catalog browsing interface.
If you decide to use the v17 leanback library for your app, you should note that it is dependent on the v4 support library. This means that apps that use the leanback support library should include all of these support libraries:
The v17 leanback library contains resources, which require you to take specific steps to include it in app projects. For instructions on importing a support library with resources, see Support Library Setup.
After you have completed the steps described above, it's time to start building apps for the big screen! Check out these additional topics to help you build your app for TV:
Running your app is an important part of the development process. The AVD Manager in the Android SDK provides the device definitions that allow you to create virtual TV devices for running and testing your applications.
To create an virtual TV device:
Note: For best performance of the TV emulator device, enable the Use Host GPU option and, where supported, use virtual device acceleration. For more information on hardware acceleration of the emulator, see Using the Emulator.
To test your application on the virtual TV device:
For more information about using emulators see, Using the Emulator. For more information on deploying apps from Android Studio to virtual devices, see Debugging with Android Studio.