Cómo controlar hardware de TV

El hardware de TV es muy diferente de otros dispositivos Android. Las TVs no incluyen algunas de las funciones de hardware que se encuentran en otros dispositivos Android, como pantallas táctiles, cámaras y receptores de GPS. Las TVs también dependen por completo de dispositivos de hardware secundarios: para que los usuarios interactúen con apps para TV, deben usar un control remoto o un control de juego. Cuando compilas una app para TV, debes tener muy en cuenta las limitaciones y los requisitos de hardware para poder operar en hardware de TV.

En esta guía, se muestra cómo comprobar si tu app se ejecuta en una TV y cómo controlar las funciones de hardware no compatibles. Para obtener información sobre los distintos métodos de entrada, consulta Cómo administrar controladores de TV.

Cómo buscar un dispositivo de TV

Si estás creando una app que funciona tanto en dispositivos de TV como en otros dispositivos, es posible que debas verificar en qué tipo de dispositivo se ejecuta la app y ajustar su funcionamiento. Por ejemplo, si tienes una app que se puede iniciar a través de un Intent, verifica las propiedades del dispositivo para determinar si debes iniciar una actividad orientada a la TV o una actividad en el teléfono.

La forma recomendada de determinar si tu app se ejecuta en un dispositivo de TV es usar el método PackageManager.hasSystemFeature() para verificar si el dispositivo se ejecuta en modo de TV. En el siguiente código de ejemplo, se muestra cómo comprobar si tu app se ejecuta en un dispositivo de TV:

Kotlin

const val TAG = "DeviceTypeRuntimeCheck"

val isTelevision = packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK)
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device")
} else {
    Log.d(TAG, "Running on a non-TV Device")
}

Java

public static final String TAG = "DeviceTypeRuntimeCheck";

boolean isTelevision = getPackageManager().hasSystemFeature(PackageManager.FEATURE_LEANBACK);
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device");
} else {
    Log.d(TAG, "Running on a non-TV Device");
}

Cómo manejar las funciones de hardware no compatibles

Según el diseño y la funcionalidad de tu app, es posible que puedas evitar el problema de que ciertas funciones de hardware no estén disponibles. En esta sección, se explica qué funciones de hardware no están disponibles para TV, cómo detectar funciones de hardware faltantes y las alternativas que se sugieren.

Funciones no compatibles para hardware de TV

Las TVs tienen un propósito diferente de otros dispositivos, por lo que no tienen las funciones de hardware que suelen tener otros dispositivos con Android. Por este motivo, el sistema Android no admite las siguientes funciones para un dispositivo de TV:

Hardware Descriptor de funciones de Android
Pantalla táctil android.hardware.touchscreen
Emulador de pantalla táctil android.hardware.faketouch
Telefonía android.hardware.telephony
Cámara android.hardware.camera
Comunicación de campo cercano (NFC) android.hardware.nfc
GPS android.hardware.location.gps
Micrófono android.hardware.microphone
Sensores android.hardware.sensor
Pantalla en orientación vertical android.hardware.screen.portrait

Nota: Algunos controladores de TV tienen un micrófono, que no es el mismo que el de la función de hardware de micrófono que se describe aquí. El micrófono del control es totalmente compatible.

Consulta la Referencia de funciones para obtener una lista completa de las funciones, las subfunciones y sus descriptores.

Cómo declarar requisitos de hardware para TV

Las apps para Android pueden declarar requisitos de funciones de hardware en el manifiesto de la app para garantizar que no se instalen en dispositivos que no incluyen esas funciones. Si estás extendiendo una app existente para su uso en TV, revisa atentamente el manifiesto de tu app para detectar cualquier declaración de requisitos de hardware que pueda impedir que se instale en un dispositivo de TV.

Si tu app usa funciones de hardware, como una pantalla táctil o una cámara, que no están disponibles en una TV, pero puede funcionar sin el uso de esas funciones, modifica el manifiesto de la app para indicar que estas funciones no son necesarias. En el siguiente fragmento de código del manifiesto, se muestra cómo declarar que tu app no requiere funciones de hardware que no están disponibles en dispositivos de TV, pero que las usa en otros dispositivos:

<uses-feature android:name="android.hardware.touchscreen"
        android:required="false"/>
<uses-feature android:name="android.hardware.faketouch"
        android:required="false"/>
<uses-feature android:name="android.hardware.telephony"
        android:required="false"/>
<uses-feature android:name="android.hardware.camera"
        android:required="false"/>
<uses-feature android:name="android.hardware.nfc"
        android:required="false"/>
<uses-feature android:name="android.hardware.location.gps"
        android:required="false"/>
<uses-feature android:name="android.hardware.microphone"
        android:required="false"/>
<uses-feature android:name="android.hardware.sensor"
        android:required="false"/>
<!-- Some TV devices have an ethernet connection only -->
<uses-feature android:name="android.hardware.wifi"
        android:required="false"/>

Nota: Algunas funciones tienen subfunciones, como android.hardware.camera.front, como se describe en Referencia de funciones. Asegúrate de marcar como required="false" las subfunciones que también se usan en tu app.

Todas las apps diseñadas para usarse en dispositivos de TV deben declarar que la función de pantalla táctil no es obligatoria, como se describe en Cómo comenzar a usar apps para TV. Si tu app normalmente usa una o más de las funciones no compatibles con dispositivos de TV, cambia la configuración del atributo android:required a false para esas funciones en tu manifiesto.

Precaución: Si declaras una función de hardware mediante la configuración de su valor en true, evitarás que tu app se instale en dispositivos de TV o que aparezca en el selector de la pantalla principal de Android TV.

Ten en cuenta los permisos que implican funciones de hardware

Algunas declaraciones del manifiesto de uses-permission llevan funciones de hardware implícitas. Este comportamiento implica que solicitar algunos permisos en el manifiesto de tu app puede impedir que esta se instale y use en dispositivos de TV. Los siguientes permisos comúnmente solicitados crean un requisito implícito de funciones de hardware:

Permiso Función implícita de hardware
RECORD_AUDIO android.hardware.microphone
CAMERA android.hardware.camera y
android.hardware.camera.autofocus
ACCESS_COARSE_LOCATION

android.hardware.location

android.hardware.location.network (nivel de API objetivo 20 o versiones anteriores únicamente)

ACCESS_FINE_LOCATION

android.hardware.location

android.hardware.location.gps (nivel de API objetivo 20 o versiones anteriores únicamente)

ACCESS_WIFI_STATE
CHANGE_WIFI_STATE

android.hardware.wifi

Algunos dispositivos de TV solo tienen conexión Ethernet.

Para obtener una lista completa de solicitudes de permisos que suponen un requisito de función de hardware, consulta la guía de uses-feature. Si tu app solicita una de las funciones mencionadas anteriormente, incluye una declaración uses-feature en tu manifiesto para la función de hardware implícita que indique que no es necesaria. android:required="false".

Nota: Si tu app se orienta a Android 5.0 (nivel de API 21) o versiones posteriores, y usa el permiso ACCESS_COARSE_LOCATION o ACCESS_FINE_LOCATION, los usuarios podrán instalarla en un dispositivo de TV aunque este no tenga una tarjeta de red ni un receptor de GPS.

Después de que las funciones de hardware sean opcionales para tu app, debes comprobar la disponibilidad de esas funciones durante el tiempo de ejecución y ajustar el comportamiento de tu app. En la siguiente sección, se explica cómo comprobar funciones de hardware y se sugieren algunos enfoques para cambiar el comportamiento de tu app.

Para obtener más información sobre cómo filtrar y declarar funciones en el manifiesto, consulta la guía de uses-feature.

Cómo buscar funciones de hardware

El framework de Android puede indicarte si hay funciones de hardware no disponibles en el dispositivo en el que se ejecuta tu app. Usa el método hasSystemFeature(String) para comprobar funciones específicas durante el tiempo de ejecución. Este método toma un solo argumento de cadena que especifica la función que deseas comprobar.

En el siguiente ejemplo de código, se muestra cómo detectar la disponibilidad de funciones de hardware en el entorno de ejecución:

Kotlin

// Check whether the telephony hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls")
}

// Check whether android.hardware.touchscreen feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.")
}

Java

// Check whether the telephony hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls");
}

// Check whether android.hardware.touchscreen feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.");
}

Pantalla táctil

Como la mayoría de las TVs no tienen pantalla táctil, Android no admite la interacción con pantallas táctiles para dispositivos de TV. Además, el uso de una pantalla táctil no es coherente con un entorno visual en el que el usuario está sentado a 3 metros de la pantalla. Asegúrate de que tus elementos de IU y texto no requieran ni impliquen el uso de una pantalla táctil.

Para dispositivos de TV, diseña tu app para que admita la navegación mediante un mando de dirección (pad direccional) en un control remoto para TV. Para obtener más información sobre cómo admitir la navegación mediante controles compatibles con la TV, consulta Navegación en TV.

Cámara

Si bien las TV no suelen tener cámara, puedes proporcionar una app relacionada con la fotografía en una TV. Por ejemplo, si tienes una app que toma, visualiza y edita fotos, puedes inhabilitar su función para tomar fotos en las TVs y seguir permitiendo que los usuarios vean y editen fotos. Si decides permitir que tu app relacionada con la cámara funcione en una TV, agrega la siguiente declaración de función en el manifiesto de tu app:

<uses-feature android:name="android.hardware.camera" android:required="false" />

Si permites que tu app se ejecute sin una cámara, agrégale código que detecte si la función de cámara está disponible y ajusta el funcionamiento de tu app. En el siguiente ejemplo de código, se muestra cómo detectar la presencia de una cámara:

Kotlin

// Check whether the camera hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!")
} else {
    Log.d("Camera test", "No camera available. View and edit features only.")
}

Java

// Check whether the camera hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!");
} else {
    Log.d("Camera test", "No camera available. View and edit features only.");
}

GPS

Las TVs son dispositivos fijos, de interior y no tienen receptores integrados de sistema de posicionamiento global (GPS). Si tu app usa información de ubicación, puedes permitir que los usuarios busquen una ubicación o usen un proveedor de ubicación estática, como un código postal establecido durante la configuración del dispositivo de TV.

Kotlin

// Request a static location from the location manager.
val locationManager = this.getSystemService(Context.LOCATION_SERVICE) as LocationManager
val location: Location = locationManager.getLastKnownLocation("static")

// Attempt to get postal code from the static location object.
val geocoder = Geocoder(this)
val address: Address? =
        try {
            geocoder.getFromLocation(location.latitude, location.longitude, 1)[0]
                    .apply {
                        Log.d(TAG, postalCode)
                    }
        } catch (e: IOException) {
            Log.e(TAG, "Geocoder error", e)
            null
        }

Java

// Request a static location from the location manager.
LocationManager locationManager = (LocationManager) this.getSystemService(
        Context.LOCATION_SERVICE);
Location location = locationManager.getLastKnownLocation("static");

// Attempt to get postal code from the static location object.
Geocoder geocoder = new Geocoder(this);
Address address = null;
try {
  address = geocoder.getFromLocation(location.getLatitude(),
          location.getLongitude(), 1).get(0);
  Log.d("Postal code", address.getPostalCode());

} catch (IOException e) {
  Log.e(TAG, "Geocoder error", e);
}

Pausa la reproducción durante el modo de bajo consumo

Algunos dispositivos de TV admiten un modo de bajo consumo cuando el usuario apaga el dispositivo. En lugar de apagarlo, el dispositivo inhabilita la pantalla y sigue ejecutando Android TV en segundo plano. La salida de audio sigue habilitada en este modo, por lo que debes detener todo el contenido que se esté reproduciendo cuando el dispositivo esté en el modo de bajo consumo.

Para evitar que se reproduzca contenido durante el modo de bajo consumo, debes anular onStop() y detener la reproducción:

Kotlin

override fun onStop() {
    // App-specific method to stop playback.
    stopPlayback()
    super.onStop()
}

Java

@Override
public void onStop() {
  // App-specific method to stop playback.
  stopPlayback();
  super.onStop();
}

Cuando el usuario vuelve a encenderlo, se llama a onStart() si tu app es la app activa en primer plano. Para obtener más información sobre cómo iniciar y detener una actividad, consulta El ciclo de vida de la actividad.