Cómo crear y ejecutar una app para TVs

Las apps para TV usan la misma estructura que las apps para teléfonos y tablets. Esta similitud significa que puedes modificar las apps existentes para que se ejecuten en dispositivos de TV o bien 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 para Android TV en Google Play. Si quieres 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 un entorno de desarrollo donde puedas crear apps para TV, además de los cambios mínimos necesarios para lograr que una app se ejecute en dispositivos de TV.

Para obtener información sobre el diseño de apps para TV, consulta Diseño para TV. También consulta las apps de muestra 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:

• 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 app para TV nueva. Si ya tienes una app para Android, agregar compatibilidad con Android TV te permite diseñar una interfaz de usuario para TV mediante la reutilización de tu arquitectura de apps existente.

Nota: Te recomendamos tener una sola app que admita tanto dispositivos móviles como de TV. Si necesitas apps individuales, puedes publicar varias apps en la misma ficha en Google Play al usando compatibilidad con varios APK. Para obtener más información, consulta Compatibilidad con varios APK.

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, declara una actividad que vaya a ejecutarse en dispositivos de TV.
• Bibliotecas para 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 crear interfaces de usuario.

Requisitos previos

Antes de comenzar a compilar una app para TV, debes seguir estos pasos:

• Actualizar las herramientas de tu 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.
• Actualizar el SDK con Android 5.0 (API 21) o una versión posterior
  La versión actualizada de la plataforma ofrece nuevas API para apps de TV.
• Crear o actualizar tu proyecto de app.
  Para acceder a las nuevas API para dispositivos de TV, crea un proyecto o modifica uno existente que se oriente a Android 5.0 (nivel de API 21) o a 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, debe usar un filtro de intent CATEGORY_LEANBACK_LAUNCHER. Este filtro identifica que tu app está 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 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 esa actividad como la 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 uses 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 parte para TV de tu app existente, debe proporcionar una navegación intuitiva con un control remoto desde 3 metros de distancia. Si modificas una app existente para su uso en TV, no uses para TV el mismo diseño de actividad que usas para teléfonos y tablets. Para obtener los lineamientos de diseño de apps para TV, consulta Diseño para TV.

Cómo declarar la compatibilidad con dispositivos de TV

Declara que tu app está diseñada para Android TV declarando la android.software.leanback función.

Si tu app se ejecuta tanto en dispositivos móviles como en TV, configura 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 apps que están diseñadas para ejecutarse en dispositivos de TV no dependen de las pantallas táctiles como método de entrada. Para dejarlo en claro, el manifiesto de tu app para TV debe declarar que no se requiere la función android.hardware.touchscreen. Esta configuración identifica a tu app como apta para ejecutarse 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 la app, debes declarar que no se requiere una pantalla táctil, según como se muestra en el siguiente ejemplo de código. De lo contrario, tu app no aparecerá en Google Play en dispositivos de TV.

Cómo proporcionar un ícono y un banner en la pantalla principal

Las apps para Android TV deben proporcionar un ícono y una imagen de banner en la pantalla principal para cada localización. Según el dispositivo Android TV, se usa el ícono o el banner como el 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 en la pantalla principal. Para 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 de íconos y banners de apps para Android TV.

Banner de la pantalla principal

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

Para el banner, usa un recurso xhdpi con un tamaño de 320 × 180 px. Se debe incluir texto en la imagen. Si tu app está disponible en varios idiomas, debes proporcionar distintas versiones 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 SplashScreen API de la plataforma 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 android:colorPrimary atributo de la app o actividad de 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 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 Temas y estilos.

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 dedicados 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 widgets de interfaz de usuario y API 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 hacerlo en dispositivos de TV configurados para que admitan la depuración por USB o usar dispositivos de TV virtuales.

Cómo ejecutar apps 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 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 veas 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 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 máximo rendimiento del dispositivo emulador de TV, usa el emulador de x86 y habilita la opción Usar GPU del host. Además, usa la aceleración de dispositivos virtuales 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.

Para obtener más información sobre el uso de 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.

Cómo habilitar la ejecución de tu app para TV como una experiencia instantánea

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

Para configurar tu app para TV para 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 aplicaciones habilitado para la función instantánea.

Luego, en el intent-filter de la MainActivity de tu app para TV, asegúrate de que se declaren LAUNCHER y LEANBACK_LAUNCHER 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

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