Cómo administrar controladores de TV

Los dispositivos de TV requieren un dispositivo de hardware secundario para interactuar con las apps: un control remoto básico, un control remoto con puntero o un control de juegos. Para proporcionar una experiencia del usuario coherente, tu app debe admitir la entrada del pad direccional (pad en forma de cruz), controlar los controles que se desconectan y admitir la entrada de varios tipos de controles, incluidos los controles remotos con puntero.

Controles mínimos para pad direccional

El control predeterminado para un dispositivo de TV es el pad direccional. En general, tu app debe poder operarse desde un control remoto que solo tenga botones de arriba, abajo, izquierda, derecha, seleccionar, atrás y de inicio. Si tu app es un juego que suele requerir un control de juegos con controles adicionales, intenta admitir el juego solo con estos controles de pad direccional. De lo contrario, advierte al usuario que se requiere un controlador y permítele salir del juego correctamente con el controlador del pad direccional.

Para obtener más información sobre la navegación con controles de pad direccional para dispositivos de TV, consulta Navegación en la TV.

Administra la desconexión de controles

Los controles para la TV suelen ser dispositivos Bluetooth, que pueden intentar ahorrar energía entrando periódicamente en modo de suspensión y desconectándose del dispositivo de la TV. Esto significa que una app podría interrumpirse o reiniciarse si no está configurada para controlar estos eventos de reconexión. Estos eventos pueden ocurrir en cualquiera de las siguientes circunstancias:

• Mientras se reproduce un video de varios minutos, es posible que el pad direccional o el control de juegos entren en modo de suspensión, se desconecten del dispositivo de TV y se vuelvan a conectar más tarde.
• Durante el juego, es posible que un jugador nuevo se una con un control de juegos que aún no esté conectado.
• Durante el juego, es posible que un jugador abandone el juego y desconecte un control de juegos.

Cualquier actividad de la app para TVs que esté sujeta a eventos de desconexión y reconexión debe configurarse para controlar los eventos de reconexión en el manifiesto de la app. En el siguiente ejemplo de código, se muestra cómo habilitar una actividad para que controle los cambios de configuración, incluida la conexión, desconexión o reconexión de un teclado o un dispositivo de navegación:

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

Este cambio de configuración permite que la app siga ejecutándose durante un evento de reconexión, en lugar de que el framework de Android la reinicie, lo que no es una buena experiencia del usuario.

Administra las variaciones de entrada de pad direccional

Es posible que los usuarios de dispositivos de TV tengan más de un tipo de control que usen con su TV. Por ejemplo, un usuario puede tener un control remoto básico con pad direccional, un control remoto con puntero o un control de juegos. Los códigos de teclas que proporciona un controlador de juegos cuando se usa para las funciones del pad direccional pueden variar de los códigos de teclas que envía un pad direccional básico.

Controla las variaciones en la entrada del pad direccional para que el usuario no tenga que cambiar de control para operar tu app. Para obtener más información sobre el control de las variaciones de entrada, consulta Cómo procesar la entrada del pad direccional.

Compatibilidad con controles remotos de puntero

Algunos dispositivos de TV admiten controles remotos con puntero, como ratones aéreos o controles remotos con pads direccionales sensibles al tacto (trackpads). La compatibilidad con controles remotos de puntero permite que los usuarios interactúen con tu app usando gestos de apuntar y hacer clic, desplazamiento, deslizamiento y arrastre, lo que proporciona una experiencia más fluida en hardware compatible y, al mismo tiempo, mantiene la compatibilidad total con el pad direccional.

Cómo declarar la compatibilidad con el control remoto de puntero en el manifiesto

Para indicar que tu app se puede navegar con entrada táctil y de puntero, configura el manifiesto de la app con el metadato android.software.leanback.supports_touch establecido en true:

<manifest ...>
    <!-- Signal whether the app is adaptive or built just for TV -->
    <uses-feature
        android:name="android.software.leanback"
        android:required="true|false" />
    <!-- Ensure the app can be installed on conventional TVs -->
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <!-- Signal whether the app supports pointer remotes -->
    <meta-data
        android:name="android.software.leanback.supports_touch"
        android:value="true" />
    <application ...>
        ...
    </application>
</manifest>

Admiten interacciones de clic, desplazamiento del mouse y desplazamiento

Cuando admitas controles remotos de puntero, asegúrate de que los componentes de la IU respondan de forma adecuada a las entradas táctiles y del cursor en las siguientes interacciones:

• Clic y selección: Todos los elementos de la IU que se pueden seleccionar y en los que se puede enfocar deben poder hacer clic con el control remoto de puntero, lo que coincide con el comportamiento de la selección con el pad direccional (KEYCODE_DPAD_CENTER).
  • Jetpack Compose: Usa los modificadores Modifier.clickable() o pointerInput. Para obtener más detalles, consulta Presionar y mantener presionado.
  • Vistas: Controlan los eventos de clic en las vistas. Para obtener más detalles, consulta la descripción general de los eventos de entrada.
• Estados visuales de desplazamiento: Proporcionan un efecto visual claro de desplazamiento para indicar cuándo el cursor del puntero se posiciona sobre un elemento seleccionable.
  • Jetpack Compose: Usa Modifier.hoverable() o observa los estados de desplazamiento con el mouse usando un InteractionSource. Para obtener más detalles, consulta Controla las interacciones del usuario.
  • Vistas: Define estados de desplazamiento con el mouse usando elementos de diseño de lista de estados con android:state_hovered="true".
• Desplazamiento con deslizamiento y lanzamiento: El desplazamiento horizontal y vertical que se activa con un gesto de deslizamiento o lanzamiento en un botón central sensible al tacto del pad direccional debe funcionar sin problemas en todo el contenido desplazable.
• Desplazamiento con arrastre: Los usuarios deben poder arrastrar para desplazarse verticalmente (hacia arriba y hacia abajo) u horizontalmente (hacia la izquierda y hacia la derecha) en los contenedores desplazables.
  • Jetpack Compose: Los contenedores desplazables estándar admiten el desplazamiento con el puntero y el desplazamiento táctil de forma predeterminada. Para implementaciones personalizadas, consulta Entrada del puntero en Compose.
  • Vistas: Las vistas desplazables estándar admiten el desplazamiento táctil de forma predeterminada. Para el control de entrada personalizado, consulta Entrada y control táctil.
• Desplazamiento en la reproducción de contenido multimedia: Durante la reproducción de contenido multimedia (como programas de TV y películas), los usuarios deben poder interactuar con la barra de progreso de la reproducción (barra de búsqueda) apuntando y haciendo clic para avanzar a una marca de tiempo pasada o futura, así como arrastrando (desplazando) la barra de progreso para buscar un momento específico.

Administra eventos de botones

Cuando el usuario hace clic en un botón del controlador, tu app recibe un evento con un objeto KeyEvent. El comportamiento previsto para el botón podría ser un evento multimedia, como reproducir, pausar o detener, o podría ser un evento de tipo TV, como selección o navegación. Para proporcionar una buena experiencia del usuario, asigna un comportamiento coherente a los botones del controlador.

Eventos de IU de TV

Asigna el comportamiento de la IU de TV a los botones que generan tipos KeyEvent, como se muestra en la siguiente tabla:

Eventos multimedia

Cuando el usuario esté mirando contenido multimedia, asigna un comportamiento a los botones que generen tipos de KeyEvent, como se muestra en la siguiente tabla. Si tu app controla un MediaSession, usa un MediaControllerAdapter para llamar a uno de los métodos MediaControllerCompat.TransportControls que se muestran en la tabla. Ten en cuenta que, en este contexto, los botones de selección funcionan como botones de reproducción o pausa.

Proporciona un comportamiento adecuado para el botón Atrás

El botón Atrás nunca debe funcionar como un botón de activación. Por ejemplo, no lo uses para abrir y cerrar un menú. Solo se usa para navegar hacia atrás, como migas de pan, por las pantallas anteriores en las que estuvo el reproductor.

Dado que el botón Atrás solo realiza una navegación lineal hacia atrás, puedes usarlo para salir de un menú integrado en la app que se abrió con otro botón y volver a la app. Presionar el botón Atrás de forma consecutiva siempre debe llevar a la pantalla principal de Android TV. Por ejemplo: Juego > Pantalla de pausa del juego > Pantalla principal del juego > Pantalla principal de Android TV o Reproducción de un programa de TV > Pantalla principal de la app de TV

Pantalla principal de Android TV.

Para obtener más información sobre el diseño de la navegación, consulta Diseño de la navegación hacia atrás y hacia arriba. Para obtener información sobre la implementación, consulta Cómo proporcionar una navegación hacia atrás adecuada.

Administración de controles para juegos

Cuando crees juegos para Android TV, diseña tu esquema de control para que funcione con los controles remotos de TV estándar y los controles de juegos exclusivos.

Admite controles de pad direccional

Planifica tu esquema de control en torno a un control de pad direccional, ya que este conjunto de controles es el predeterminado para los dispositivos Android TV. El jugador debe poder usar un pad direccional para todos los aspectos del juego, no solo para controlar la jugabilidad principal, sino también para navegar por los menús y los anuncios. Por este motivo, asegúrate de que tu juego para Android TV no haga referencia a una interfaz táctil con un lenguaje como "Presiona aquí para continuar".

La forma en que moldeas la interacción del jugador con el controlador puede ser clave para lograr una excelente experiencia del usuario. Analiza las siguientes prácticas recomendadas:

• Comunica los requisitos del control por adelantado: Usa la descripción de Google Play para comunicar al jugador las expectativas sobre los controles. Si un juego es más adecuado para un gamepad con una palanca de control que para uno con solo un pad direccional, indícalo claramente. Un jugador que usa un control inadecuado para un juego podría tener una mala experiencia y darle una mala calificación a tu juego.
• Usa una asignación de botones coherente: La asignación intuitiva de botones es clave para una buena experiencia del usuario. Por ejemplo, usa el botón A para aceptar y el botón B para cancelar, de acuerdo con las costumbres aceptadas. También puedes ofrecer flexibilidad permitiendo que el usuario reasigne los botones. Para obtener más información sobre la asignación de botones, consulta Cómo controlar las acciones del controlador.
• Detecta las capacidades del control y ajústalas según corresponda: Consulta al control sobre sus capacidades para optimizar la compatibilidad entre el control y el juego. Por ejemplo, es posible que quieras que un jugador dirija un objeto agitando el control en el aire, pero si el control de un jugador no tiene hardware de acelerómetro y giroscopio, agitarlo no funcionará. Consulta el controlador y, si no se admite la detección de movimiento, cambia a un esquema de control alternativo disponible. Para obtener más información sobre cómo consultar las capacidades del controlador, consulta Compatibilidad con controladores en diferentes versiones de Android.

Usa los botones correctos

No todos los controles de juego tienen los botones Inicio, Búsqueda o Menú. Asegúrate de que tu IU no dependa del uso de estos botones.

Administra varios controles

Cuando varios jugadores están jugando un juego, cada uno con su propio control, es importante asignar cada par jugador-control. Para obtener información sobre cómo implementar la identificación de números de controlador, consulta getControllerNumber().

Administra la desconexión de controles

Cuando se desconecta un control en medio del juego, pausa el juego y muestra un diálogo en el que se le solicita al jugador desconectado que vuelva a conectar su control.

También ofrece sugerencias para solucionar problemas en el diálogo. Por ejemplo, dile al reproductor que "compruebe la conexión Bluetooth". Para obtener más información sobre cómo implementar la compatibilidad con dispositivos de entrada, consulta Cómo controlar las acciones del controlador y la Descripción general de Bluetooth.

Muestra instrucciones del control

Si tu juego proporciona instrucciones visuales para el control del juego, usa una imagen del control sin marcas y que solo incluya botones compatibles con Android.

Para ver imágenes de muestra de un control compatible con Android, descarga la plantilla de gamepad de Android TV (ZIP). Incluye un controlador blanco sobre un fondo negro y un controlador negro sobre un fondo blanco (que se muestran en la figura 1) como un archivo PNG y como un archivo de Adobe® Illustrator®.