Cómo crear y ejecutar una app para TVs

Las apps para TVs 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 la compilació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 indican en Calidad de las apps para TVs.

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

Para obtener información sobre el diseño de apps para TVs, consulta Diseño para TVs. También puedes consultar 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 los códecs, los protocolos y los formatos compatibles con Android TV:

• Formatos multimedia compatibles
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

Cómo configurar un proyecto para TV

En esta sección, se explica cómo configurar un proyecto para TV, ya sea que modifiques una app para Android existente para que se ejecute en dispositivos de TV o que crees una nueva app para TV. Si tienes una app para Android existente, agregar compatibilidad con Android TV te permite diseñar una interfaz de usuario para TV y reutilizar la arquitectura de tu 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 esté diseñada para ejecutarse en dispositivos de TV.
• Bibliotecas de TV: De manera opcional, incluye 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 compilar una app para TVs, debes seguir estos pasos:

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

Cómo declarar una actividad para TV

En su manifiesto, una aplicación diseñada para ejecutarse en dispositivos de TV debe declarar una actividad de selector para TV. Para ello, usa un filtro de intents CATEGORY_LEANBACK_LAUNCHER. Este filtro identifica tu app como habilitada para TVs y permite que Google Play la identifique como una app para TVs. 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>

La segunda entrada del manifiesto de actividad en este ejemplo especifica que es la actividad que se debe 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 la verán. Además, si tu app no tiene este filtro cuando usas herramientas para desarrolladores para cargarla en un dispositivo de TV, no aparecerá en la interfaz de usuario de la TV.

La interfaz de usuario de tu app para TVs, o la parte para TVs de tu app existente, debe proporcionar una navegación intuitiva con un control remoto desde una distancia de 3 metros. Si modificas una app existente para usarla en la TV, no uses el mismo diseño de actividad para la TV que usas para teléfonos y tablets. Si deseas obtener instrucciones para diseñar una app para TV, consulta Diseño para TVs.

Cómo declarar la compatibilidad con dispositivos de TV

Declara que tu app está diseñada para Android TV declarando 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 estableces el valor del atributo required en true, Google Play solo pondrá tu app a disposición del SO de 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 las pantallas táctiles para la entrada. Para que esto quede claro, el manifiesto de tu app para TVs debe declarar que la función android.hardware.touchscreen no es obligatoria. Este parámetro de configuración identifica tu app como apta para funcionar en un dispositivo de TV y es obligatorio para que se considere una app para TV 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 para TVs.

Proporciona un ícono y un banner para 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 agregar estos elementos 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

Al igual que todas las apps para Android, las apps para Android TV deben proporcionar un ícono para la pantalla principal. Si deseas conocer las prácticas recomendadas para diseñar un excelente punto de inicio para tu app y los requisitos detallados de los recursos, consulta los lineamientos sobre el ícono y el banner de la app para Android TV.

Banner de la pantalla principal

Usa el atributo android:banner con la etiqueta <application> para proporcionar un banner predeterminado para todas las actividades de la aplicación o 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 × 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 admitido.

Cómo cambiar el color del selector

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

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

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

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

Jetpack incluye bibliotecas de paquetes de AndroidX para usarlas con apps para TV.

Compose para TV

Compose es la forma recomendada de compilar apps para el SO Android TV. Junto con las bibliotecas principales de Compose, las bibliotecas de Compose para TV proporcionan componentes específicos diseñados especialmente para la pantalla grande:

• androidx.tv.foundation
• androidx.tv.material

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 la IU de Leanback

El kit de herramientas de la IU de Leanback proporciona APIs y widgets de la interfaz de usuario para dispositivos de TV:

• androidx.leanback.app
• androidx.leanback.database
• androidx.leanback.graphics
• androidx.leanback.media
• androidx.leanback.preference
• androidx.leanback.system
• androidx.leanback.widget
• androidx.leanback.widget.picker

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

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.

Ejecuta 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 que proporcionó 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 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 aplicaciones.

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 x86 y habilita la opción Usar GPU del host. También usa la aceleración del dispositivo virtual 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.

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 cómo implementar apps desde Android Studio en dispositivos virtuales, consulta Cómo depurar tu app.

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

Las experiencias instantáneas permiten que los usuarios prueben tu app para TVs sin instalarla y pueden ayudar a aumentar su adopción.

Para configurar tu app para TVs 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 compatible con apps instantáneas.

A continuación, en el intent-filter del MainActivity de tu app para TVs, 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 TVs ahora está configurada para ejecutarse como experiencia instantánea.

Prepara tu app para TVs para su publicación

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