Android TV Developer Guide

Target Android TV with development tips and tricks from NVIDIA in the Android TV Developer Guide.
Google launched Android TV at Google I/O 2014 formally opening up the living room and TV to brand new Android experiences. Use the guide below to learn how to enhance and optimize your Android games and applications for this exciting Android platform.
Use the resources below to set you down the right path to success on both Android TV & NVIDIA SHIELD!
To quickly check if your app is ready to go on Android TV, check the Android TV Deployment Checklist.
The NVIDIA SHIELD family of Android devices includes the SHIELD console, the ultimate living room entertainment device. Powered by the NVIDIA Tegra X1 for blazing performance, the SHIELD console is the world's first 4K Android TV device and provides the best Android development platform on the market.
For more details, check out the SHIELD developer page.
- Android TV's New Opportunities
- Controller Support
- Starter Guide
- Controller Inputs
- Support Remote Controls & Multiple Controllers
- Use Consistent Controls
- Display Controller Instructions
- Android TV Graphics Considerations
- Android TV UI Considerations
- Support Landscape
- The 10 Foot TV Experience
- UI Indicators
- Controllable Components
- Overscan
- Remove Irrelevant Options
- Android Manifest Setup
Android TV's New Opportunities
Android TV and the coupling of large screen TVs with increasingly powerful mobile processors, like NVIDIA Tegra processors, opens a host of new opportunities for game and application developers. Here are some ideas to get you thinking about how to differentiate on Android TV.
Large Screen UI or Android TV Specific Layout
If the Leanback Launcher is in play, you're probably running with a quality game controller or on a big screen like a TV. If so, can you switch over to a different UI for Android TV and try out some of those ideas that your UI designer came up with that just didn't work on a small screen?
Local Multiplayer
Android TV with its ability to pair with all sorts of controllers just screams out for multiplayer and party games. Think about how your game could utilize multiple controllers to provide friends with the ability to split the TV screen (for shooters and racing games) or all join in some big screen madness (think Bomberman or sports games).
Multiple Views
For 3D games and applications, you may be able to subdivide the TV screen to provide additional view points or camera angles (eg a rear view mirror). Or if you're already maxing out 3D, when Android TV is detected, look to add helpful overlays or 2D elements to the edges of the screen such as maps, lap times or itinerary load-outs.
Controller Support
Users interact with Android TV solely with a game controller, remote control or other DPAD style controller. Games and apps need to properly support controllers for all operations. This includes all menus, sub menus, options screens and use of the app and for gameplay. In addition, verify that all middleware, especially in-app advertising systems, have full controller support and do not assume a touchscreen is present.
Starter Guide
Start using game controllers in Android fast with NVIDIA's Game Controller Quick Start Guide. The guide includes notes for native/UE4 and Unity developers. For a native code sample, check out the game controller project in the TDK samples pack included with the SHIELD SDK.
Controller Inputs
No custom code required! Use standard Android game controller input sources for your game and UI. Users should obviously be able to play the game but must also be able to do everything else with the controller (e.g. navigate menus, start games, pause, adjust settings).
Support Remote Controls & Multiple Controllers

Many Android TV devices reside in the living room and are setup with multiple game controllers. Don't assume there is a single input source and encourage users to play with friends and family by supporting two, three, four or as many controllers as possible! Check the NVIDIA controller guide for instructions on how to correctly address each input device and be sure to handle disconnects gracefully (e.g. by pausing the game and letting the user reconnect).
Android TV also introduces Android remotes, such as the SHIELD remote, which have a subset of buttons compared to a full game controller. To expand the reach of a game on Android TV, developers should support both game controllers and remotes by accepting the minimal set of buttons where possible (see the table at the bottom of the Controller Guide FAQ).
Use Consistent Controls
For menus and UI dialogs, use a logical, consistent scheme. To cater for both game controllers and DPAD style remote controls, we advise:
- DPAD directions for navigation (KEYCODE_DPAD_*)
- KEYCODE_BUTTON_A and KEYCODE_DPAD_CENTER for confirmation (i.e. accept both)
- KEYCODE_BACK (and preferably also accept KEYCODE_BUTTON_B in UI and menus) for cancel or back
Display Controller Instructions
Show players how to play the game or use the app with a clear on-screen controller image indicating what each button and control stick does. To assist developers, NVIDIA provides the SHIELD controller line art
and renders available with and without button call-outs as PNG, PSD and AI files.
Download the SHIELD controller graphics and add them to your game!
Google also makes a generic controller graphic available from the Android TV guide: "Building TV Games".
Android TV Graphics Considerations
As screens go from small phones to large TVs, developers need to consider a range of new issues.
Small vs Large Screens
TV's are big! Does the stretch from a 5" to 50" to 150" screen show graphical weaknesses?
- Check the look of your textures; low resolution textures often look poor when stretched on Android TV.
- Do the 3D models have jagged edged curves on the TV due to too few polygons?
- Particle effects may need reworking for the TV's big screen if there are too few emitters, patterns or colors.
- Anti-aliasing is often not required on Android devices with small screens with high pixel density but consider turning out for the TV.
Google also has some good guidelines on this topic.
Pixels Galore
Android TV devices typically output at the TV's native resolution. How does your app perform at 1080p? What about 4K? Remember that a small increase in resolution numbers can have a huge increase in the number total of pixels (e.g. 720p has less than 1 million pixels vs 1080p which has over 2 million).
To better handle a range of resolutions, consider techniques such as dynamically setting the resolution (see the note below) or the quality levels for things such as shaders, shadows and texture filtering. If performance is still an issue, check out NVIDIA's profiling tools to help look for bottlenecks and analyze the rendering pipeline.
ANativeWindow_setBuffersGeometry
.
For a native code sample, check out the Dynamic Resolution project in the TDK samples included with the CodeWorks package.
Android TV UI Considerations
Consider customizing the UI to take advantage of the larger screen size a TV provides.
Support Landscape
Android TV outputs to screen using landscape screen orientation so be sure to support landscape throughout the app.
> The application and all activities must support landscape orientation. Even a single activity that does not support landscape will filter your app out of Play Store results on Android TV devices.
In particular, confirm that no activity in the app includes an android:screenOrientation
of: portrait
, reversePortrait
, sensorPortrait
, userPortrait
or reverseLandscape
.
The 10 Foot TV Experience
Check the "10 foot" experience: that is, how does the game look on a TV whilst sitting on the couch? Run the game or app on the SHIELD Android TV device, or plug a SHIELD portable or SHIELD tablet into a TV using HDMI:
- Can you read all text clearly on the TV screen?
- Are the buttons and UI graphics too small or too large?
- Can you do everything with just the controller and without having to get up to look at the tablet or tap the screen?
UI Indicators
Use highlights, glows, resizing, or otherwise make it clear what UI element the user has selected. If possible, also make it clear if an element becomes non-actionable or non-focusable.
Controllable Components
Make all the UI components usable with a controller (don't forget the less common things like drop-down lists, sliders & tabs).
Overscan

Unlike phone and tablet screens, TV's can lose some space at the edges of the screen to overscan. Although many TV's now use fixed-pixel technologies like LCD, many brands still lose edge detail. Be sure to leave a region around the outside of the TV screen free from important UI and gameplay elements. A good rule-of-thumb is to have a 5-10% margin of totally free space and a 10-20% margin before drawing important elements.
If you are using standard Android components for your UI, you can use the built-in overscan support that was made available in Android Jellybean. If the UI is custom OpenGL or OpenGL ES code, or is using a game engine's UI system, you will have to cater for overscan in your Android TV interface design.
The slickest way of handling overscan is to offer a configuration mode (perhaps via an options menu) that draws a box around the edge of the display. In some cases, because of overscan, part or all of the box will not be visible to the user. Prompt the user to shrink the box's edges using the controller until they see each edge. This box can then be used for placement of UI elements and can allow precise corner placements.
Remove Irrelevant Options
Many games include control or customization options for sensors or components not present or relevant to a TV. For custom Android TV releases or when Android TV is detected, consider removing or disabling options such as accelerometer steering or touch sensitivity.
Android Manifest Setup
For Android TV, Google implemented a new interface and launcher called the Leanback Launcher which provides a customized 10-foot experience. There are some specific manifest requirements for Android TV without which your app will not be listed on the Android TV Play Store.
To quickly check if your app is ready to go on Android TV, check the Android TV Deployment Checklist.
Leanback Activity Declaration & Intent
Games and apps that are designed for Android TV must add a second activity specifically for the Leanback Launcher. To correctly add this support:
- Add a manifest declaration that the app uses the Leanback Launcher. If the same apk runs on Android TV and other Android devices, be sure to set the required attribute to
false
. If required istrue
, the app will only appear on Android TV devices. - Add the
android.intent.category.LEANBACK_LAUNCHER
intent filter to a second activity in the application declaration of the manifest. This activity can be a separate entry point for TV users if you want to customize the experience.
LEANBACK_LAUNCHER
intent filter in the AndroidManifest.xml
as it is used by Play Store for filtering. If it is missing, Play Store does not show the app to Android TV users in search results.
<manifest> <-- Declare the app can use Leanback Launcher --> <uses-feature android:name="android.software.leanback" android:required="false" /> ... <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> <-- Define the second Android TV specific activity --> <activity android:name="com.example.android.TvActivity" android:label="@string/app_name" android:theme="@style/Theme.Leanback"> <-- Register the second launch point for the Leanback Launcher --> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LEANBACK_LAUNCHER" /> </intent-filter> </activity> ... </application> </manifest>
Leanback Launcher Banner
To launch each app, Android TV uses a banner graphic measuring 320x180 pixels included in the APK. The banner can be specified at the application
level or, if desired, each activity
can have its own banner. Note that the banner is displayed "as-is" with no extra text added so app names should be included if desired.
<application ... android:logo:="drawable resource" > <activity ... android:logo:="drawable resource" > ... </activity> ... </application>
No Touchscreen
Up until now Android ran mainly on phones and tablets which have touchscreens. As such, Play Store assumes apps need a touchscreen unless the manifest states otherwise. You must set the touchscreen feature to false in the Android manifest for Android TV games and apps that support game controllers and remotes.
<uses-feature android:name="android.hardware.touchscreen" android:required="false" />
touchscreen required false
declaration in the AndroidManifest.xml
as it is used by Play Store for filtering. If it is missing, Play Store does not show the app to Android TV users in search results.
Game Controller Flag
Android TV uses at least DPAD be supported for input but many apps go further and have full controller support. To let the system inform the user if a game controller is required, you must include the following entry in the Android manifest:
<uses-feature android:name="android.hardware.gamepad" />
If you support a game controller but also provide full functionality with a remote or otherwise do not require a full controller, add android:required="false"
to the declaration:
<uses-feature android:name="android.hardware.gamepad" android:required="false" />
Game Flag
If you're a game, shout about it! Add the "isGame" meta-data flag inside the application block of the Android manifest file. The launcher tracks apps with this flag and displays them in a separate location in the launcher.
<manifest ...> <application ...> ... <android:isGame="true"> ... </application> </manifest>
Limited Sensors
Android TV devices do not include all the hardware features Android developers may be used to. Be careful with the uses-feature
element. Requiring GPS, accelerometer or other sensors found in phones and tablets but not present in Android TV devices removes the listing from search results on Android TV. If you are using a sensor but it is not crucial to operation, be sure to set the required flag to false.
<manifest ...> <application ...> ... <!-- Requiring the camera removes this listing from Android TV search results --> <uses-feature android:name="android.hardware.camera" android:required="true" /> <!-- Making accelerometer optional has no impact on Android TV filtering --> <uses-feature android:name="android.hardware.sensor.accelerometer" android:required="false" /> </application> </manifest>
Implied Features
In addition to explicit features, certain app permissions also come with an implied feature requirement that Play Store uses for filtering. For instance, the ACCESS_FINE_LOCATION
permission implies uses-feature android.hardware.location.gps
and any device that does not include a GPS (i.e. Android TV devices) do not show your app in search results.
Make sure the Android manifest isn't limiting the target market and excluding Android TV devices.
<manifest ...> ... <!-- Is this really needed? --> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"> </uses-permission> <!-- This casts a much wider net --> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"> </uses-permission> </manifest>
TV Screen Sizes
TV's may present a new set of screen sizes to your app. Carefully follow Google's detailed Supporting Multiple Screens API guide.
Also note that "compatible screens" listed in the Android manifest limit the devices that can install your application. Verify you actually need to include "compatible screens" and if you do, include all the sizes you support.
For more information, check the Android SDK documentation for supports-screens
and compatible-screens
.