Cómo controlar hardware de TV

El hardware de TV es muy diferente de otros dispositivos Android. Las TV 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 juegos. (Para obtener más información sobre los distintos métodos de entrada, consulta Cómo administrar controladores de TV).

Cuando crees una app para TV, ten en cuenta las limitaciones y los requisitos de hardware para que pueda funcionar en hardware de TV. Verifica si tu app se ejecuta en una TV y controla funciones de hardware no compatibles.

Cómo buscar un dispositivo de TV

Si estás compilando una app que funciona tanto en dispositivos de TV como en otros dispositivos, es posible que debas verificar en qué tipo de dispositivo se está ejecutando y ajustar su funcionamiento. Por ejemplo, si tienes una app que puede iniciarse mediante un Intent, comprueba las propiedades del dispositivo para determinar si debes iniciar una actividad orientada a una TV o una actividad de 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 comprobar 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:

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")
}

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 que ciertas funciones de hardware no estén disponibles. En esta sección, se explica qué funciones de hardware no suelen estar disponibles para TV, cómo detectar funciones de hardware faltantes y qué alternativas se sugieren a estas funciones.

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 otros dispositivos con Android suelen tener. Por este motivo, el sistema Android no admite las siguientes funciones para un dispositivo de TV:

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 controlador es totalmente compatible.

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

Declara los requisitos de hardware para TV

Las apps para Android pueden declarar requisitos de funciones de hardware en el manifiesto de la app para ayudar a garantizar que no se instalen en dispositivos que no tengan esas funciones. Si quieres extender una app existente para su uso en TV, revisa cuidadosamente el manifiesto de tu app en busca de declaraciones de requisitos de hardware que puedan impedir que se instale en un dispositivo de TV.

Si tu app usa funciones de hardware, como una pantalla táctil o cámara, que no están disponibles en la TV, pero puede funcionar sin esas funciones, modifica el manifiesto de la app para indicar que estas funciones no son necesarias. En el siguiente fragmento de código de manifiesto, se muestra cómo declarar que tu app no requiere funciones de hardware que no están disponibles en dispositivos de TV, pero 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 creadas 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 suele usar 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 el establecimiento 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 implican funciones de hardware. Este comportamiento significa 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:

Para obtener una lista completa de solicitudes de permisos que implican 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 indica 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 pueden instalar tu app en un dispositivo de TV, incluso si este no tiene una tarjeta de red ni un receptor de GPS.

Después de hacer que las funciones de hardware sean opcionales para tu app, debes comprobar la disponibilidad de esas funciones durante el tiempo de ejecución y, luego, 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 quieres verificar.

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

// 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.")
}

// 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, usar 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.

En el caso de dispositivos de TV, diseña tu app de modo 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 con controles compatibles con la TV, consulta Navegación para 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, ve y edita fotos, puedes inhabilitar su función de toma de fotos para TVs y seguir permitiendo que los usuarios las vean y editen. 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 la 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 realice ajustes en el funcionamiento de la app. En el siguiente ejemplo de código, se muestra cómo detectar la presencia de una cámara:

// 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.")
}

// 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 TV 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, aún puedes permitir que los usuarios busquen una ubicación o usen un proveedor de ubicación estático, como un código postal establecido durante la configuración del dispositivo de TV.

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

// 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 el modo de bajo consumo cuando el usuario apaga el dispositivo. En lugar de apagarse, el dispositivo inhabilita la pantalla y sigue ejecutando Android TV en segundo plano. La salida de audio todavía está habilitada en este modo, por lo que debes detener cualquier contenido que se esté reproduciendo cuando el dispositivo esté en el modo de bajo consumo.

Para evitar la reproducción durante el modo de bajo consumo, anula onStop() y detén cualquier contenido que se esté reproduciendo:

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

@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 Ciclo de vida de la actividad.