Android TV Developer Guide and optimization guide for NVIDIA SHIELD devices

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.

SHIELD: The Ultimate Android TV Device!

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

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?

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.

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).

Controller Support

Users interact with Android TV solely with a game controller 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 or gameplay. In addition, verify that all middleware, especially in-app advertising systems, have full controller support and do not assume a touchscreen is present.

Controller Inputs

Use standard Android game controller input sources for your game and UI. Users should obviously be able to play your game but must also be able to do everything else with the controller (e.g. navigate menus, start games, pause, adjust settings).

Accept DPAD & Buttons

For menus and UI dialogs, be sure to accept:

  • DPAD directions for navigation
  • BUTTON_A for confirmation
  • BACK (and preferably BUTTON_B) for cancel or back

Starter Guide

Start using game controllers in Android fast with NVIDIA's Game Controller Quick Start Guide. The guide includes notes for native and Unity developers. For a native code sample, check out the game controller project in the TDK samples pack included with TADP.

Graphics Considerations on Android TV

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.

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).

Check out NVIDIA's profiling tools to help look for bottlenecks and analyze performance.

> Resolution Scaling: For 3D applications and games moving to Android TV, consider fixing the renderable resolution or providing a setting or slider to adjust the size of the render target. You can achieve this quite simply and enable the GPU's 2D hardware scaler to do the required stretching using ANativeWindow_setBuffersGeometry.

For a native code sample, check out the Dynamic Resolution project in the TDK samples included with the Tegra Android Development Pack.

UI Considerations on Android TV

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? Plug an Android TV device, 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. Be sure to leave a region around the outside of the TV screen free from important UI and gameplay 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 an engine's UI system, you will have to cater for overscan in your Android TV interface design.

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.

> To better interpret and understand your Android manifest, check out NVIDIA's handy Android Manifest Validator tool.

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:

  1. 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 is true, the app will only appear on Android TV devices.
  2. 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.
> You must include the 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"/>
> You must include the 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 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 ...>
    ...
    <uses-feature android:name="android.hardware.camera" 
      android:required="true" />  <!-- Requiring the camera removes this 
                                             listing from Android TV search results -->
    <uses-feature android:name="android.hardware.sensor.accelerometer" 
      android:required="false" /> <!-- Making accelerometer optional 
                                             has no impact on Android TV filtering -->
  </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 ...>
  ...
  <uses-permission 
    android:name="android.permission.ACCESS_FINE_LOCATION">   <!-- Is this really needed? -->
  </uses-permission> 
  <uses-permission 
    android:name="android.permission.ACCESS_COARSE_LOCATION"> <!-- This casts a much wider net -->
  </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.