Cómo comenzar a usar apps para TV

Las apps para TV usan la misma estructura que las apps para teléfonos y tablets. Esta similitud significa que puedes modificar tus apps existentes para que también se ejecuten en dispositivos de TV o crear apps nuevas en función de lo que ya sabes sobre creación de apps para Android.

Importante: Tu app debe cumplir con requisitos específicos para calificar como app para Android TV en Google Play. Para obtener más información, consulta los requisitos que se detallan en Calidad de las apps para TV.

En esta guía, se describe cómo preparar tu entorno de desarrollo para crear apps para TV y los cambios mínimos necesarios para permitir que una app se ejecute en dispositivos de TV.

Para obtener información sobre cómo diseñar apps para TV, consulta Cómo diseñar para TV. También consulta las apps de ejemplo en el repositorio de GitHub de Android TV.

Cómo determinar la compatibilidad con formatos multimedia

Consulta la siguiente documentación para obtener información sobre códecs, protocolos y formatos compatibles con Android TV:

Cómo configurar un proyecto para TV

En esta sección, se explica cómo configurar un proyecto de TV, ya sea que quieras modificar una app de Android existente para que se ejecute en dispositivos de TV o crear una nueva. Si ya tienes una app para Android, agregar compatibilidad con Android TV te permite diseñar una interfaz de usuario para TV y reutilizar la arquitectura de tu app existente.

Cómo declarar una actividad para TV

Una aplicación diseñada para ejecutarse en dispositivos de TV debe declarar una actividad de lanzamiento para TV en su manifiesto. Para ello, usa un filtro de intents CATEGORY_LEANBACK_LAUNCHER. Este filtro identifica tu app como habilitada para TV y permite que Google Play la identifique como app de TV. Cuando un usuario selecciona tu app en la pantalla principal de la TV, este intent identifica qué actividad iniciar.

En el siguiente fragmento de código, se muestra cómo incluir este filtro de intent en tu manifiesto:

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

  <activity
    android:name="com.example.android.TvActivity"
    android:label="@string/app_name"
    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>
</application>

En la segunda entrada del manifiesto de la actividad en este ejemplo, se especifica que es la actividad que se iniciará en un dispositivo de TV.

Precaución: Si no incluyes el filtro de intents CATEGORY_LEANBACK_LAUNCHER en tu app, los usuarios que ejecuten Google Play en dispositivos de TV no podrán verlo. Además, si tu app no tiene este filtro cuando usas herramientas para desarrolladores para cargarla en un dispositivo de TV, la app no aparecerá en la interfaz de usuario de la TV.

La interfaz de usuario de tu app para TV, o la parte para TV de tu app existente, debe proporcionar una interfaz simple para navegar fácilmente con un control remoto a 3 metros de distancia. Si modificas una app existente para su uso en TV, no uses el mismo diseño de actividad para TV que usas en teléfonos y tablets. Para conocer los lineamientos sobre cómo diseñar una app para TV, consulta Cómo diseñar para TV. Si quieres obtener más información sobre los requisitos mínimos de implementación para diseños de interfaces de TV, consulta Cómo compilar diseños de TV.

Cómo declarar la compatibilidad con dispositivos de TV

Declara que tu app se diseñó para Android TV. Para ello, declara la función android.software.leanback.

Si tu app se ejecuta en dispositivos móviles y TVs, establece el valor del atributo required en false. Si configuras el valor del atributo required en true, Google Play solo hará que tu app esté disponible en el SO Android TV. 

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

Cómo declarar la pantalla táctil como no obligatoria

Las aplicaciones que están diseñadas para ejecutarse en dispositivos de TV no dependen de pantallas táctiles como método de entrada. Para que quede claro, el manifiesto de tu app para TV debe declarar que no se requiere la función android.hardware.touchscreen. Esta configuración identifica que tu app puede funcionar en un dispositivo de TV, y es necesaria para que se considere como tal en Google Play. El siguiente ejemplo de código muestra cómo incluir esta declaración de manifiesto: 

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

Precaución: En el manifiesto de tu app, debes declarar que no se requiere una pantalla táctil, como se muestra en este código de ejemplo. De lo contrario, tu app no aparecerá en Google Play en dispositivos de TV.

Proporciona un ícono y un banner en la pantalla principal

Las apps para Android TV deben proporcionar un ícono de pantalla principal y una imagen de banner para cada localización. Según el dispositivo Android TV, se usa el ícono o el banner como punto de inicio de la app que aparece en la pantalla principal en las filas de apps y juegos.

Para agregarlos a tu app, describe el ícono y el banner en el manifiesto de la siguiente manera: 

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

Ícono de la pantalla principal

Las apps para Android TV, al igual que todas las apps para Android, deben proporcionar un ícono de pantalla principal. Si quieres conocer las prácticas recomendadas para diseñar un buen punto de lanzamiento para tu app y conocer los requisitos detallados de los elementos, consulta los lineamientos de íconos y banners de la app para Android TV.

Usa el atributo android:banner con la etiqueta <application> para proporcionar un banner predeterminado a todas las actividades de la aplicación, o bien con la etiqueta <activity> para proporcionar un banner para una actividad específica.

Para el banner, usa un recurso xhdpi con un tamaño de 320 x 180 px. Se debe incluir texto en la imagen. Si tu app está disponible en más de un idioma, debes proporcionar versiones separadas del banner con texto para cada idioma admitido.

Cómo cambiar el color del selector

Precaución: En Android 12 y versiones posteriores, las animaciones de la pantalla de presentación personalizadas compiladas con la API de la plataforma SplashScreen no son compatibles con las apps para Android TV.

Cuando se inicia una app para TV, el sistema muestra una animación similar a un círculo relleno que se expande. Para personalizar el color de esta animación, configura el atributo android:colorPrimary de tu app o actividad para TV en un color específico. Además, establece dos atributos de superposición de transición en true, como se muestra en el siguiente fragmento de un archivo en formato XML de recursos de temas:

<resources>
    <style ... >
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>

Para obtener más información sobre cómo trabajar con temas y estilos, consulta Estilos y temas.

Cómo compilar una app para el SO Android TV

La mayoría de las bibliotecas de AndroidX se pueden usar con Android TV. Usa componentes de la arquitectura, como ViewModel, para administrar datos de la IU optimizados para ciclos de vida, y Room para realizar la integración con bases de datos SQLite locales, como lo harías con dispositivos móviles.

La mayoría de las bibliotecas de AndroidX son compatibles con Android TV. Las apps para TV pueden usar los mismos componentes de arquitectura que las apps para dispositivos móviles. Incluso puedes compartir componentes entre factores de forma, por lo que solo necesitas especializar la lógica de presentación de tu app para TV.

Compose para TV

Usa Jetpack Compose para compilar la IU de tu SO para TV. Compose es la herramienta moderna de Android para el desarrollo de IU. Junto con las bibliotecas principales de Compose, las bibliotecas de Compose para TV proporcionan componentes dedicados diseñados especialmente para la pantalla grande:

Descubre cómo compilar una app para TV con Compose para TV en Cómo usar Jetpack Compose en Android TV.

Kit de herramientas de IU de Leanback (no recomendable)

Históricamente, el kit de herramientas de la IU de Leanback ha proporcionado APIs y widgets de interfaz de usuario exclusivamente para dispositivos de TV que usan vistas y fragmentos de Android:

Descubre cómo compilar una app para TV con el kit de herramientas de la IU de Leanback en Cómo usar el kit de herramientas de la IU de Leanback.

Cómo ejecutar apps para TV

Ejecutar tu app es una parte fundamental del proceso de desarrollo. Puedes ejecutar tu app en dispositivos de TV configurados para admitir la depuración por USB o usar dispositivos de TV virtuales.

Cómo ejecutar la app en un dispositivo físico

Configura tu dispositivo de la siguiente manera:

  1. Usa un cable USB para conectar tu dispositivo de TV a la máquina de desarrollo. Si es necesario, consulta la documentación proporcionada por el fabricante de tu dispositivo.
  2. En tu dispositivo de TV, navega a Configuración.
  3. En la fila Dispositivo, selecciona Acerca de.
  4. Desplázate hasta Compilación y selecciona Compilación varias veces hasta que aparezca el mensaje "Ya eres desarrollador".
  5. Vuelve a Configuración. En la fila Preferencias, selecciona Opciones para desarrolladores.
  6. Selecciona Depuración > Depuración de USB y haz clic en Activada.
  7. Vuelve a la pantalla principal de la TV.

Para probar tu app en un dispositivo de TV, haz lo siguiente:

  1. En Android Studio, selecciona tu proyecto y haz clic en Run en la barra de herramientas.
  2. En la ventana Select Deployment Target, selecciona tu dispositivo de TV y haz clic en OK.

Cómo ejecutar apps en un dispositivo virtual

El Administrador de AVD en el SDK de Android proporciona definiciones de dispositivos que te permiten crear dispositivos de TV virtuales para ejecutar y probar tus apps.

Para crear un dispositivo de TV virtual, haz lo siguiente:

  1. Inicia el Administrador de AVD. Para obtener más información, consulta Cómo crear y administrar dispositivos virtuales.
  2. En el diálogo del Administrador de AVD, haz clic en la pestaña Definiciones de dispositivos.
  3. Selecciona una de las definiciones de dispositivos Android TV y haz clic en Crear AVD.
  4. Selecciona las opciones del emulador y haz clic en Aceptar para crear el AVD.

    Nota: Para obtener el mejor rendimiento del dispositivo emulador de TV, usa el emulador de x86 y habilita la opción Use Host GPU. Además, usa la aceleración de dispositivo virtual cuando esté disponible. Para obtener más información sobre la aceleración de hardware del emulador, consulta Cómo configurar la aceleración de hardware para Android Emulator.

Para probar tu app en el dispositivo de TV virtual, sigue estos pasos:

  1. En Android Studio, selecciona tu proyecto y haz clic en Run en la barra de herramientas.
  2. En la ventana Select Deployment Target, selecciona tu dispositivo de TV virtual y haz clic en OK.

Si quieres obtener más información para usar emuladores, consulta Cómo ejecutar apps en Android Emulator. Para obtener más información sobre la implementación de apps desde Android Studio en dispositivos virtuales, consulta Cómo depurar tu app.

Habilita tu app para TVs de modo que se ejecute como una experiencia instantánea

Las experiencias instantáneas permiten que los usuarios prueben tu app para TV con facilidad, lo que puede ayudar a aumentar la adopción.

Si quieres configurar tu app para TV de modo que se ejecute como una app instantánea en un dispositivo o emulador de Android TV, primero sigue las instrucciones para crear un paquete de aplicación instantánea.

A continuación, en el intent-filter del MainActivity de tu app para TV, asegúrate de que LAUNCHER y LEANBACK_LAUNCHER estén declarados en AndroidManifest.xml: 

<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" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
  </activity>

Tu app para TV ya está configurada para ejecutarse como una experiencia instantánea.

Cómo preparar tu app para TV para publicarla

Revisa la lista de tareas de apps para TV a fin de conocer los próximos pasos y preparar tu app para TV para su publicación y distribución.