TV devices require a secondary hardware device for interacting with apps, in the form of a basic remote controller or game controller. This means that your app must support D-pad input. It also means that your app may need to handle controllers going offline and input from more than one type of controller.
This lesson discusses the requirements for handling controllers for TV devices.
D-pad minimum controls
The default controller for a TV device is a D-pad. In general, your app should be operable from a remote controller that only has up, down, left, right, select, Back, and Home buttons. If your app is a game that typically requires a game controller with additional controls, your app should attempt to allow gameplay with these D-pad controls. In this case, your app should also warn the user that a controller is required and allow them to exit your game gracefully using the D-pad controller. For more information about handling navigation with D-pad controller for TV devices, see Create TV navigation.
Handle controller disconnects
Controllers for TV are frequently Bluetooth devices which may attempt to save power by periodically going into sleep mode and disconnecting from the TV device. This means that an app might be interrupted or restarted if it is not configured to handle these reconnect events. These events can happen in any of the following circumstances:
- While watching a video which is several minutes long, a D-Pad or game controller goes into sleep mode, disconnects from the TV device and then reconnects later on.
- During gameplay, a new player joins the game using a game controller that is not currently connected.
- During gameplay, a player leaves the game and disconnects a game controller.
Any TV app activity that is subject to disconnect and reconnect events must be configured to handle reconnection events in the app manifest. The following code sample demonstrates how to enable an activity to handle configuration changes, including a keyboard or navigation device connecting, disconnecting, or reconnecting:
<activity
android:name="com.example.android.TvActivity"
android:label="@string/app_name"
android:configChanges="keyboard|keyboardHidden|navigation"
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>
This configuration change allows the app to continue running through a reconnection event, rather than being restarted by the Android framework, which is not a good user experience.
Handle D-pad input variations
TV device users may have more than one type of controller that they use with their TV. For example, a user might have both a basic D-pad controller and a game controller. The key codes provided by a game controller when it is being used for D-pad functions may vary from the key codes sent by a physical D-pad.
Your app should handle the variations of D-pad input from a game controller, so the user does not have to physically switch controllers to operate your app. For more information on handling these input variations, see Handle controller actions.
Handle button events
When the user clicks a button on a controller, your app receives an event with a KeyEvent. The intended behavior for the button might be a media event (like play, pause, or stop) or it could be a TV-type event (like selection or navigation). In order to provide a good user experience, your app should assign consistent behavior to controller buttons.
TV UI events
Buttons that generate these KeyEvents should be handled by the app according to table below.
| KeyEvent | Behavior |
|---|---|
| BUTTON_B, BACK | Back |
| BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER, KEYCODE_NUMPAD_ENTER | Selection |
| DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT | Navigation |
Media events
When the user is watching media, buttons that generate these KeyEvents
should be handled by your app according to the table below. If your app is controlling a
MediaSession, it should
use a MediaControllerAdapter
to call one of the MediaControllerCompat.TransportControls
methods as shown below. Note that the selection buttons act as Play/Pause buttons in this context.
| KeyEvent | TransportControls call | Behavior |
|---|---|---|
| BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER, KEYCODE_NUMPAD_ENTER | pause() | Play |
| BUTTON_START, BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER, KEYCODE_NUMPAD_ENTER | pause() | Pause |
| BUTTON_R1 | skipToNext() | Skip to next |
| BUTTON_L1 | skipToPrevious() | Skip to previous |
| DPAD_RIGHT, BUTTON_R2, AXIS_RTRIGGER, AXIS_THROTTLE | fastForward() | Fast forward |
| DPAD_LEFT, BUTTON_L2, AXIS_LTRIGGER, AXIS_BRAKE | rewind() | Rewind |
| (No KeyEvent is associated with Stop) | stop() | Stop |
Note: When you use a MediaSession, you should not override the handling of
media-specific buttons such as
KEYCODE_MEDIA_PLAY
or KEYCODE_MEDIA_PAUSE.
The system will automatically trigger the appropriate
MediaSession.Callback
method.
Provide appropriate Back-button behavior
The Back button should never act as a toggle. For example, do not use it to both open and close a menu. It should only navigate backward, breadcrumb-style, through the previous screens the player has been on. Since the Back button should only perform linear (backward) navigation, you may use the back button to leave an in-app menu (opened by a different button) and return to the app. Consecutively pressing the back-button should always eventually lead to the Android TV home screen. For example: Game play > Game pause screen > Game main screen > Android TV home screen, or TV Show play > TV app main screen > Android TV Home screen.
For more information about design for navigation, see Navigation with back and up. To learn about implementation, refer to Provide proper back navigation.
Handle controllers for games
Support D-pad controls
Plan your control scheme around a directional pad (D-pad) control, since this control set is the default for Android TV devices. The player needs to be able to use a D-Pad in all aspects of the game—not just controlling core gameplay, but also navigating menus and ads. For this reason, you should also ensure that your Android TV game does not refer to a touch interface. For example, an Android TV game should not tell a player to "Tap here to continue."
How you shape the player's interaction with the controller can be key to achieving a great user experience:
- Communicate Controller Requirements up Front. Use your Google Play description to communicate to the player any expectations about controllers. If a game is better suited to a gamepad with a joystick than one with only a D-pad, make this fact clear. A player who uses an ill-suited controller for a game is likely to have a subpar experience and penalize your game in the ratings.
- Use Consistent Button Mapping. Intuitive and flexible button mapping is key to a good user experience. For example, you should adhere to accepted customs by using the A button to Accept, and the B button to Cancel. You can also offer flexibility in the form of remappability. For more information about button mapping, see Handle controller actions.
- Detect Controller Capabilities and Adjust Accordingly. Query the controller about its capabilities in order to optimize the match between controller and game. For example, you may intend for a player to steer an object by waving the controller in the air. If a player's controller lacks accelerometer and gyroscope hardware, however, waving will not work. So, your game should query the controller and if motion detection is not supported, switch over to an alternative, available control scheme. For more information about querying controller capabilities, see Support controllers across Android versions.
Use appropriate buttons
Not all game controllers provide Start, Search, or Menu buttons. Be sure your UI does not depend upon the use of these buttons.
Handle multiple controllers
When multiple players are playing a game, each with their own controller, it is important to
map each player-controller pair. For information about how to implement controller-number
identification, see
getControllerNumber().
Handle controller disconnects
When a controller is disconnected in the middle of gameplay, the game should pause, and a dialog should appear prompting the disconnected player to reconnect their controller.
The dialog should also offer troubleshooting tips (for example, a pop-up dialog telling the player to "Check your Bluetooth connection"). For more information about implementing input-device support, see Handle controller actions. See the Bluetooth overview for additional information.
Show controller instructions
If your game provides visual game control instructions, the controller image should be free of branding and include only buttons compatible with Android.
For sample images of an Android-compatible controller, download the Android TV Gamepad Template (ZIP). It includes a white controller on black background and a black controller on white background (shown in figure 1), as a PNG file and an Adobe® Illustrator® file.
Figure 1. Example controller instructions using the
Android TV Gamepad Template (ZIP).