Cómo administrar controladores de TV

Los dispositivos de TV requieren un dispositivo de hardware secundario para interactuar con apps, como un control remoto básico o un control de juego. Por lo tanto, tu app debe admitir la entrada de pad direccional (D-pad). Además, es posible que tu app deba administrar los controles que se desconectan y las entradas de más de un tipo de control.

En esta guía, se analizan los requisitos de administración de controladores para dispositivos de TV.

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 los botones de arriba, abajo, izquierda, derecha, seleccionar, inicio y atrás. Si tu app es un juego que generalmente requiere un control de juego con controles adicionales, intenta admitir el juego solo con estos controles del pad direccional. De lo contrario, advierte al usuario que se necesita un control y permítele salir del juego sin problemas con el control de pad direccional.

Para obtener más información sobre cómo controlar la navegación con el controlador de pad direccional para dispositivos de TV, consulta Navegación en TV.

Administra la desconexión de controles

Los controladores para TV suelen ser dispositivos Bluetooth, que pueden intentar ahorrar energía al entrar en modo de suspensión y desconectarse del dispositivo de TV. Esto significa que una app puede interrumpirse o reiniciarse si no se configura para admitir estos eventos de reconexión. Estos eventos pueden ocurrir en cualquiera de las siguientes circunstancias:

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

Cualquier actividad de la app para TV que esté sujeta a eventos de desconexión y reconexión debe configurarse de modo que maneje los eventos de reconexión en el manifiesto de la app. En la siguiente muestra de código, se indica cómo habilitar una actividad para controlar los cambios de configuración, incluido un teclado o un dispositivo de navegación que se conecte, desconecte o se reconecte:

<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 continúe ejecutándose a través de un evento de reconexión, en lugar de reiniciarse por el framework de Android, lo que no supone una buena experiencia del usuario.

Administra las variaciones de entrada de pad direccional

Los usuarios de dispositivos de TV pueden tener más de un tipo de control que usan con su TV. Por ejemplo, un usuario puede tener un control de pad direccional básico y un control de juego. Los códigos clave que proporciona un control de juego cuando se usa para las funciones de un pad direccional pueden variar con respecto a los códigos clave que envía un pad direccional básico.

Controla las variaciones en la entrada de pad direccional de modo que el usuario no tenga que cambiar de controlador para usar tu app. Si quieres obtener más información sobre cómo controlar las variaciones de entrada, consulta Cómo procesar la entrada de un mando de dirección.

Administra eventos de botones

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

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:

KeyEventComportamiento
KEYCODE_BUTTON_B, KEYCODE_BACKAtrás
KEYCODE_BUTTON_SELECT, KEYCODE_BUTTON_A, KEYCODE_ENTER, KEYCODE_DPAD_CENTER y KEYCODE_NUMPAD_ENTERSelección
KEYCODE_DPAD_UP, KEYCODE_DPAD_DOWN, KEYCODE_DPAD_LEFT y KEYCODE_DPAD_RIGHTNavigation

Eventos multimedia

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

KeyEventLlamada de TransportControlsComportamiento
BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER y KEYCODE_NUMPAD_ENTER play()Reproducir
BUTTON_START, BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER y KEYCODE_NUMPAD_ENTER pause()Pausar
BUTTON_R1skipToNext()Siguiente
BUTTON_L1skipToPrevious()Anterior
DPAD_RIGHT, BUTTON_R2, AXIS_RTRIGGER y AXIS_THROTTLEfastForward()Cinta que adelanta
DPAD_LEFT, BUTTON_L2, AXIS_LTRIGGER y AXIS_BRAKErewind()Retroceder
N/Astop()Detener

Nota: Cuando uses un MediaSession, no anules el control de botones específicos de contenido multimedia, como KEYCODE_MEDIA_PLAY o KEYCODE_MEDIA_PAUSE. El sistema activa automáticamente el método MediaSession.Callback apropiado.

Proporciona el comportamiento adecuado del 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ú al mismo tiempo. Úsalo solo para navegar hacia atrás, como una ruta de navegación, 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 dejar abierto un menú integrado en la app con otro botón y volver a la app. Si presionas consecutivamente el botón Atrás, siempre debes dirigirte 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 del programa de TV > pantalla principal de la app para TV > pantalla principal de Android TV.

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

Administración de controles para juegos

Admite controles de pad direccional

Planifica tu esquema de control en torno a un control de pad direccional, ya que este conjunto 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 el juego principal, sino también para navegar por los menús y los anuncios. Por este motivo, asegúrate de que el juego para Android TV no haga referencia a una interfaz táctil con lenguaje como "Presiona aquí para continuar".

La manera en que diseñas la interacción del jugador con el control puede ser clave para lograr una excelente experiencia del usuario. Considera las siguientes prácticas recomendadas:

  • Comunica los requisitos de los controles de antemano:Usa tu descripción de Google Play para comunicar al jugador las expectativas relacionadas con los controles. Deja en claro si el juego es más adecuado para un control de juegos con joystick que para un pad direccional. Un jugador que usa un control inadecuado para un juego puede 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, adáptate a las costumbres aceptadas; usa el botón A para aceptar y el botón B para cancelar. También puedes ofrecer flexibilidad en forma de reasignación. Para obtener más información sobre la asignación de botones, consulta Cómo administrar las acciones del control.
  • Detecta las funciones del control y realiza ajustes en consecuencia: Consulta al control sobre sus capacidades para optimizar la coincidencia entre el control y el juego. Por ejemplo, podrías querer que un jugador dirija un objeto moviendo el control en el aire, pero si el control no tiene acelerómetro ni hardware de giroscopio, mover la mano no funciona. Consulta al control y, si la detección de movimiento no es compatible, cambia a un esquema de control alternativo disponible. Si quieres obtener más información para consultar las funciones del control, consulta Cómo brindar compatibilidad con controles 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 juegan un juego y cada uno tiene su propio control, es importante asignar cada par de jugador y controlador. Para obtener información sobre cómo implementar la identificación control-número, consulta getControllerNumber().

Administra la desconexión de controles

Cuando se desconecta un control en medio de un juego, páusalo y muestra un diálogo para que el jugador desconectado vuelva a conectar su control.

Además, ofrece sugerencias para solucionar problemas en el cuadro de diálogo. Por ejemplo, dile al jugador que verifique la conexión Bluetooth. Para obtener más información sobre la implementación de compatibilidad con dispositivos de entrada, consulta Cómo administrar las acciones del control y la descripción general de Bluetooth.

Muestra instrucciones del control

Si tu juego proporciona instrucciones visuales para el control, usa una imagen de control sin elementos de marca y solo incluye botones compatibles con Android.

Para obtener imágenes de ejemplo de un control compatible con Android, descarga la Plantilla para control de juegos de Android TV (ZIP). Incluye un control blanco sobre un fondo negro y un control negro sobre un fondo blanco, que se muestra en la figura 1, como archivo PNG y como archivo de Adobe® Illustrator®.

Figura 1: Ejemplo de instrucciones del control con la plantilla del control de juegos de Android TV