Se usó la API de Cloud Translation para traducir esta página.

Cómo crear y ejecutar una app 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 bien crear apps nuevas basadas en lo que ya sobre cómo crear apps para Android.

Importante: La app debe cumplir con requisitos específicos para lo siguiente: califican como app de Android TV en Google Play. Para obtener más información, consulta los requisitos en calidad de apps para TV.

En esta guía, se describe cómo preparar tu entorno de desarrollo para crear aplicaciones para TV y el 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 Diseño para TV. TV. Consulta también las apps de ejemplo en la Repositorio de GitHub para 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 aborda cómo configurar un proyecto de TV, ya sea modificar una aplicación para Android existente para que se ejecute en dispositivos de TV, o crear una nueva app para TV. Si ya tienes una app para Android, agregar compatibilidad con Android TV te permite diseñar una interfaz de usuario para TV y, al mismo tiempo, 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 app, puedes hacer lo siguiente: declarar una actividad diseñada para ejecutarse en dispositivos de TV
Bibliotecas de TV: de manera opcional, puedes incluir uno o más de los 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 app para TV, debes seguir estos pasos:

Actualiza las herramientas del SDK a la versión 24.0.0 o a una versión posterior.
Las herramientas del SDK actualizadas te permiten crear 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 las nuevas API para dispositivos de TV, crea un proyecto o modifica uno existente proyecto que tenga como objetivo 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 iniciadora para TV. en su manifiesto. Usa un intent CATEGORY_LEANBACK_LAUNCHER. filtro para hacerlo. Este filtro identifica que tu aplicación está habilitada para TV y te permite Google Play la identificará como una app para TV. Cuando un usuario selecciona tu app en la pantalla principal de su 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 la actividad en este ejemplo especifica que es la actividad que iniciar en un dispositivo de TV.

Precaución: Si no incluyes los Filtro de intents CATEGORY_LEANBACK_LAUNCHER en tu app, no es visible para los usuarios que ejecutan Google Play en dispositivos de TV. Además, si tus app no tiene este filtro cuando usas herramientas para desarrolladores para cargarla en un dispositivo de TV, la app no aparece 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 facilitar la navegación. con un control remoto desde 3 metros de distancia. Si estás modificando una app existente para su uso en TV, no uses esta diseño de actividad para TV que se usa 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.

Cómo declarar la compatibilidad con dispositivos de TV

Declara que tu app se diseñó para Android TV. Para ello, declara el 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, haz lo siguiente: 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 el La función android.hardware.touchscreen no es necesaria. Este parámetro de configuración identifica a tu app como puede funcionar en un dispositivo de TV, y es necesario para que tu app se considere una app para TV en Google Reproducir. 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 TV dispositivos.

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 para iniciar la app. punto que aparece en la pantalla de inicio 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. Para conocer las prácticas recomendadas un buen punto de lanzamiento para tu app y requisitos detallados de los elementos, consulta el Ícono y banner de la app para Android TV lineamientos.

Usa la android:banner. con el <application> etiqueta, para proporcionar un banner predeterminado a todas las actividades de la aplicación, o con el <activity> etiqueta 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. El texto debe incluirse en las imagen. Si tu app está disponible en más de un idioma, debes proporcionar versiones separadas de las 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 el elemento La API de la plataforma SplashScreen no es compatible con apps para Android TV.

Cuando se inicia una app para TV, el sistema muestra una animación similar a un relleno relleno círculo. Para personalizar el color de esta animación, establece el android:colorPrimary de la app o actividad para TV a un color específico. Además, establece dos atributos de superposición de transición a true, como se muestra en el siguiente fragmento de un Archivo 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

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 la versión principal de Compose las bibliotecas de Compose para TV brindan componentes dedicados diseñados especialmente para el 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

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

Descubre cómo compilar una app para TV con el kit de herramientas de IU de Leanback en Cómo compilar 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 Dispositivos de TV configurados para admitir la depuración por USB o usar dispositivos de TV virtual

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

Configura tu dispositivo de la siguiente manera:

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.
En tu dispositivo de TV, navega a Configuración.
En la fila Dispositivo, selecciona Acerca de.
Desplázate hasta Compilación y selecciona Compilación varias veces hasta que veas el mensaje. "¡Ya eres desarrollador!"
Vuelve a Configuración. En la fila Preferencias, selecciona Opciones para desarrolladores.
Selecciona Depuración > Depuración de USB y haz clic en Activada.
Vuelve a la pantalla principal de la TV.

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

En Android Studio, selecciona tu proyecto y haz clic en Ejecutar en la barra de herramientas.
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 Android SDK 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:

Inicia el Administrador de AVD. Para obtener más información, consulta Crea y administra dispositivos virtuales.
En el diálogo del Administrador de AVD, haz clic en la pestaña Definiciones de dispositivos.
Selecciona una de las definiciones de dispositivos Android TV y haz clic en Crear AVD.
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 la GPU del host. Además, usa la aceleración de dispositivo virtual cuando disponibles. Para obtener más información sobre la aceleración de hardware del emulador, consulta Configura la aceleración de hardware para el Android Emulator

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

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

Para obtener más información sobre el uso de emuladores, consulta Ejecuta apps en Android Emulator. Obtén más información sobre la implementación de apps de Android Studio en entornos virtuales dispositivos, 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 facilitan el trabajo de los usuarios para que pruebes tu app para TV y aumente la adopción.

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

Luego, en el intent-filter de la app de TV MainActivity, asegúrate de que tanto LAUNCHER como Los LEANBACK_LAUNCHER se declaran 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 para conocer los próximos pasos a fin de preparar tu app para TV para su publicación y distribución.

Cómo controlar hardware de TV