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 compilación de apps para Android.

Importante: Tu app debe cumplir con requisitos específicos para calificar como app de 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 a fin de crear apps para TV y los cambios mínimos necesarios para permitir que una app se ejecute en dispositivos de TV.

Si quieres obtener información para diseñar apps para TV, consulta Diseño para TV y Cómo crear diseños de TV. Si deseas revisar una app de ejemplo para TV, consulta la app de ejemplo de Android Leanback 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 modificando una app para Android existente a fin de que se ejecute en dispositivos de TV o creando una nueva. Si tienes una app para Android existente, agregar compatibilidad con Android TV te permite diseñar una interfaz de usuario para TV mientras reutilizas tu arquitectura de app existente.

Hay dos componentes principales que usas cuando creas una app que se ejecuta en dispositivos de TV:

  • Actividad para TV: En el manifiesto de tu aplicación, declara una actividad que sea para ejecutarse en dispositivos de TV.
  • Bibliotecas para TV: De manera opcional, puedes incluir una o más de las bibliotecas de AndroidX disponibles para dispositivos de TV, que se enumeran en otra sección de esta guía. Estas bibliotecas proporcionan widgets para compilar interfaces de usuario.

Requisitos previos

Antes de comenzar a crear una aplicación para TV, debes seguir estos pasos:

  • Actualiza las herramientas del SDK a la versión 24.0.0 o una posterior.
    Las herramientas del SDK actualizadas te permiten compilar y probar apps para TV.
  • Actualiza tu SDK con Android 5.0 (nivel de API 21) o una versión posterior.
    La versión actualizada de la plataforma proporciona nuevas APIs para apps para TV.
  • Crea o actualiza el proyecto de tu app.
    Para acceder a nuevas APIs para dispositivos de TV, crea un proyecto o modifica uno existente que se oriente a Android 5.0 (nivel de API 21) o una versión posterior.

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 que tu app está habilitada para TV y permite que Google Play la identifique como una app para TV. Cuando un usuario selecciona tu app en la pantalla principal de la TV, este intent identifica qué actividad se debe 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 que aparece 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 a fin de 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 sección para TV de tu app existente, debe proporcionar una interfaz simple que facilite la navegación con un control remoto a 3 metros de distancia. Si modificas una app existente para usarla en TV, no uses el mismo diseño de actividad para TV que en teléfonos y tablets. Para obtener los lineamientos de diseño de apps para TV, consulta Diseño para TV. Si quieres obtener más información sobre los requisitos mínimos de implementación para diseños de interfaces para TV, consulta Cómo crear diseños de TV.

Cómo declarar la compatibilidad con Leanback

Declara que tu app usa la interfaz de usuario de Leanback que se necesita para Android TV. Si tu app se ejecuta tanto en dispositivos móviles como en Android TV, establece el valor del atributo required en false. Si configuras el valor del atributo required en true, tu app solo podrá ejecutarse en dispositivos que usen la IU de Leanback.

<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. Este parámetro de configuración identifica que tu app puede funcionar en un dispositivo de TV y es necesaria para que se la 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 para dispositivos de TV.

Proporciona un ícono y un banner en la pantalla principal

Las apps de 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 pantalla principal

Las apps para Android TV, como todas las apps para Android, deben proporcionar un ícono de pantalla principal. Si deseas conocer las prácticas recomendadas para diseñar un punto de lanzamiento excelente para tu app y los requisitos detallados de los elementos, consulta los lineamientos sobre íconos y banners de apps 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 con la etiqueta <activity> para proporcionar un banner a una actividad específica.

Para el banner, usa un recurso xhdpi con un tamaño de 320 x 180 px. El texto debe incluirse 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 compatible.

Cómo cambiar el color del selector

Precaución: En Android 12 y versiones posteriores, las animaciones de pantalla de presentación personalizadas compiladas con la API de la plataforma SplashScreen no son compatibles con apps de 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 agregar bibliotecas para TV

Jetpack incluye bibliotecas de paquetes de AndroidX para usarlas con apps para TV. Estas bibliotecas proporcionan APIs y widgets de interfaz de usuario para dispositivos de TV:

Cómo compilar apps para TV

Una vez que completes los pasos enumerados anteriormente, es hora de comenzar a compilar apps para la pantalla grande. Echa un vistazo a estos temas adicionales que te ayudarán a crear tu app para TV:

  • Cómo crear apps de reproducción para TV: Las TVs están diseñadas para entretener, por lo que Android proporciona un conjunto de widgets y herramientas de interfaz de usuario para crear apps para TV que reproduzcan videos y música, y permitan a los usuarios explorar el contenido que quieran.
  • Ayuda a los usuarios a encontrar tu contenido en Android TV: Con todas las opciones de contenido al alcance de sus manos, ayudar a los usuarios a encontrar contenido que les guste es casi tan importante como proporcionarlo. En esta guía, se explica cómo presentar tu contenido en dispositivos de TV.
  • Cómo crear juegos para TV: Los dispositivos de TV son plataformas geniales para juegos. Consulta este tema si quieres obtener más información sobre cómo crear excelentes experiencias de juego en la TV.
  • Cómo crear servicios de entrada de TV: Presenta el contenido de tu video con un estilo de "transmisión de TV" lineal con canales y programas a los que tus usuarios puedan acceder mediante una guía de programación y los botones para subir o bajar de canal.

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 real

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 del dispositivo.
  2. En tu dispositivo de TV, navega a Configuración.
  3. En la fila Dispositivo, selecciona Acerca de.
  4. Desplázate hacia abajo hasta Compilación y selecciona Compilación varias veces hasta que veas el mensaje "Ahora 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 dispositivos virtuales cuando esté disponible. Si deseas 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.

Para obtener más información sobre cómo 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.

Cómo permitir que tu app para TV se ejecute como una experiencia instantánea

Las experiencias instantáneas permiten que los usuarios prueben tu app para TV fácilmente y pueden ayudar a aumentar la adopción.

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

Luego, en la intent-filter del MainActivity de tu app para TV, asegúrate de que tanto LAUNCHER como 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 su publicación

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