Android TV Developer Guide

To quickly check if your app is ready to go on Android TV, check the Android TV Deployment Checklist.

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.

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 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:

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.

<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" />

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.