Android TV app preparation

Android TV app preparation

• Dealing with TV hardware
• Check TV equipment on the app
• Handle unsupported hardware features
• Declaring hardware requirements for TV
• Declaring a permission means that the hardware must have the feature
• Check Hardware Features
• Handling Controller Disconnect Scenarios

Dealing with TV hardware

TV hardware is vastly different from other Android devices. The TV doesn't include some hardware features found on other Android devices, such as touchscreens, cameras, and GPS receivers. TVs also rely entirely on secondary hardware devices. In order for users to interact with the TV app, they must use a remote or gamepad. When you build an application for the TV, you must carefully consider the hardware constraints and requirements for operating the TV hardware.

Check TV equipment on the app

If you are building an app to run on TV devices and other devices, you may need to check what kind of devices your app is running on and what operations may be performed in your app.

For example, if you have an app launched by an Intent, your app should check the device properties to determine whether it can start the activity on the TV or the activity on the phone.

Recommend a way to determine if your app is running on a TV device,

Check if the device is running in TV mode by using the UiModeManager.getCurrentModeType() method.

The following sample code shows how to check if your application is running on a TV device:

Handle unsupported hardware features

Depending on the design and functionality of the application, you may be able to work around the unavailability of certain hardware features. Learn what hardware features are typically not used with TVs, how to detect missing hardware features, and recommend using them.

• Unsupported TV hardware features

TVs have a different role than other devices, so they don't have some hardware features that other android devices usually have. For this reason, the Android system does not support TV devices with the following characteristics:

Hardware	Android feature descriptor
Touchscreen	android.hardware.touchscreen
Touchscreen emulator	android.hardware.faketouch
Telephony	android.hardware.telephony
Camera	android.hardware.camera
Near Field Communications (NFC)	android.hardware.nfc
GPS	android.hardware.location.gps
Microphone [1]	android.hardware.microphone
Sensors	android.hardware.sensor
Screen in portrait orientation	android.hardware.screen.portrait

Some TV controllers have a microphone, the microphone is not the same as the hardware feature description. Controller microphones are fully supported.

Declaring hardware requirements for TV

Android applications can declare hardware function requirements in the app Manifest to ensure that they are not installed under this app, and the device does not provide these functions. If you are extending an existing application for use on a TV, check your application's manifest carefully, as any hardware requirements declared may prevent it from being installed on a TV device.

If your application uses hardware features (such as touchscreen or camera) that are not available on the TV, but can not use these features, modify your application's manifest to indicate that these features are not required by the application. The following listing snippet demonstrates how to declare that an application does not require hardware features that are not available on a TV device, even if the application can use those features on a device without a TV:

For some features like android.hardware.camera subfeatures.front, when the feature boots, make sure to mark required="false" in any subfeatures, because it may be used in the app

For all apps to be used on a TV, the app must declare that the touchscreen features described are not required for use. If your application normally uses one or more of the features listed above, in your manifest file, change these features like android:required attribute setting to false,

Warning: Declaring a hardware feature can prevent your app from being installed on TV devices or appearing on the Android TV launcher startup page by setting some attribute values ​​​​to true

Once you decide to make your hardware features optional to your application, you must check the availability of these features at runtime and then adjust your application's behavior.

Declaring a permission means that the hardware must have the feature

Some uses-permission manifest declarations imply hardware features. This behavior means requesting some application permission list can include your app to be installed and used from TV devices. The following general request permissions create implicit hardware feature requirements:

Permission	Implied hardware feature
RECORD_AUDIO	android.hardware.microphone
CAMERA	android.hardware.camera and android.hardware.camera.autofocus
ACCESS_COARSE_LOCATION	android.hardware.location android.hardware.location.network (Target API level 20 or lower only.)
ACCESS_FINE_LOCATION	android.hardware.location android.hardware.location.gps (Target API level 20 or lower only.)

For a complete list of permissions requested, implying hardware feature requirements, see the uses-feature guide. If your app requests one of the features listed above, include a uses-feature declaration in your manifest to indicate that the hardware feature is not required (android:required="false").

Note: If your target app runs Android 5.0 (API level 21) or higher, and uses the ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permission, users can still install your app on TV devices, even if the TV device does not have a network card or GPS receiver.

Check Hardware Features

The Android framework can tell you if there are no hardware features available on the device that the application is running on. Use the hasSystemFeature(String) method to check for a specific feature at runtime. The method accepts a string parameter specifying the features you want to check.

The following code example demonstrates how to detect the availability of hardware features at runtime:

Touch screen

Since most TVs do not have touch screens, Android does not support touch-screen interactive TV devices. Also, using a touchscreen is not compatible with viewing environments where the user is sitting 10 feet away from the display. Make sure your UI elements and text do not require or imply the use of a touchscreen.

For TV devices, you should design your application to use this interaction model by supporting navigation with the directional stick (direction keys) on a TV remote.

Camera

While TVs usually don't have cameras, you can still offer a photography-related TV app. For example, if you have an application that needs to view and edit photos, you can disable its camera functionality and even allow the user to view and edit photos. If you decide to make camera-related apps work on TVs, add the following capability declaration to your app manifest:

If you don't have a camera, enable the app to add runtime code to your app that detects if camera functionality is available and enables to adjust the app's operation. The following code example demonstrates how to detect the presence of a camera:

GPS

The TV is a stationary, indoor unit that does not have a built-in Global Positioning System (GPS) receiver. If your application uses location information, you can still allow users to search for a location, or use a static location provider such as zip code in the TV device's configuration settings.

Handling Controllers

TV devices require ancillary hardware devices to interact with applications, a basic form of remote controller or game controller. This means that your application must support arrow key input. This also means that your app needs to handle the controller offline and input from an external device (such as a keyboard), rather than one type of controller (a normal remote).

Arrow keys minimum control

The default controller for TV devices is a D-pad. In general, applications should be operable only from a remote controller with the down, left, right, select, and home buttons. If your application is a game that typically requires control with additional game controllers, the application should attempt to make the game controllable with these arrow keys. In this case, the app should also remind the user that a controller is required and allow them to exit your game gracefully using the D-pad controller.

Handling Controller Disconnect Scenarios

The controller on the TV may be disconnected, such as the Bluetooth device may periodically enter sleep mode or disconnect from the TV device to save power. This means that the application may be interrupted or restarted if it is not configured to handle these connection events. These events can occur in one of the following situations:

• When watching a video that is several minutes long, the D-pad or game controller goes into sleep mode, disconnects from the TV device, and then reconnects.
• While in the game, a new player joins the game using a game controller that is not currently connected.
• While in the game, the player leaves the game and disconnects the game controller.

Any activity in the app on the TV is conditional on disconnection and reconnection events, and must be configured to handle reconnection events. In the app's Mainfest file, the following code example demonstrates how to enable an Activity to handle configuration changes, including To connect, disconnect, or reconnect a keyboard or navigation device: