Gerenciar controles de TV

Os dispositivos de TV exigem um dispositivo de hardware secundário para interagir com apps: um controle remoto básico ou controle de jogo. Portanto, seu app precisa oferecer suporte à entrada por botão direcional. Além disso, seu app pode precisar lidar com controladores que ficam off-line e entradas de mais de um tipo de controlador.

Este guia discute os requisitos para o tratamento de controladores para dispositivos de TV.

Controles D-pad mínimos

O controlador padrão para um dispositivo de TV é um D-pad. Em geral, o app precisa ser operado em um controle remoto que tenha apenas os botões para cima, para baixo, para a esquerda, para a direita, selecionar, voltar e iniciar. Se o app for um jogo que normalmente exige um controle com outros controles, tente oferecer suporte ao jogo apenas com esses controles D-pad. Caso contrário, avise ao usuário que um controle é necessário e permita que ele saia do jogo usando o controlador D-pad.

Para saber mais sobre como processar a navegação com o controlador D-pad para dispositivos de TV, consulte Navegação na TV.

Tratar desconexões do controlador

Controladores para TV são frequentemente dispositivos Bluetooth, que podem tentar economizar energia entrando periodicamente no modo de suspensão e desconectando-se do dispositivo de TV. Isso significa que um app poderá ser interrompido ou reiniciado se não estiver configurado para processar esses eventos de reconexão. Esses eventos podem acontecer em qualquer uma das seguintes circunstâncias:

  • Durante um vídeo com vários minutos de duração, um botão direcional ou controlador de jogo pode entrar no modo de suspensão, desconectar do dispositivo de TV e se reconectar mais tarde.
  • Durante o jogo, um novo jogador pode usar um controle que ainda não esteja conectado.
  • Durante o jogo, um jogador pode sair e desconectar um controle de jogo.

Qualquer atividade de app de TV sujeita a eventos de desconexão e reconexão precisa ser configurada para processar eventos de reconexão no manifesto do app. O exemplo de código a seguir demonstra como permitir que uma atividade processe mudanças de configuração, incluindo um teclado ou dispositivo de navegação conectado, desconectado ou reconectado:

<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>

Essa mudança de configuração permite que o app continue a ser executado em um evento de reconexão, em vez de ser reiniciado pelo framework do Android, o que não é uma boa experiência do usuário.

Gerenciar variações de entradas do D-pad

Os usuários de dispositivos de TV podem ter mais de um tipo de controle para usar com a TV. Por exemplo, um usuário pode ter um controlador D-pad básico e um controlador de jogo. Os códigos fornecidos por um controle de jogo quando ele está sendo usado para funções D-pad podem variar dos códigos enviados por um botão direcional básico.

Gerencie as variações na entrada do botão direcional para que o usuário não precise alternar entre os controles para operar o app. Para saber mais sobre como processar variações de entrada, consulte Processar entradas do botão direcional.

Gerenciar eventos de botão

Quando o usuário clica em um botão em um controlador, seu app recebe um evento com um KeyEvent. O comportamento pretendido para o botão pode ser um evento de mídia, como reproduzir, pausar ou parar, ou pode ser um evento do tipo TV, como seleção ou navegação. Para oferecer uma boa experiência ao usuário, atribua um comportamento consistente aos botões de controle.

Eventos de IU da TV

Atribua o comportamento da IU da TV aos botões que geram tipos KeyEvent, conforme mostrado na tabela abaixo:

KeyEventComportamento
KEYCODE_BUTTON_B, KEYCODE_BACKVoltar
KEYCODE_BUTTON_SELECT, KEYCODE_BUTTON_A, KEYCODE_ENTER, KEYCODE_DPAD_CENTER e KEYCODE_NUMPAD_ENTERSeleção
KEYCODE_DPAD_UP, KEYCODE_DPAD_DOWN, KEYCODE_DPAD_LEFT, KEYCODE_DPAD_RIGHTNavegação

Eventos de mídia

Quando o usuário estiver assistindo mídia, atribua um comportamento aos botões que geram tipos de KeyEvent, conforme mostrado na tabela abaixo. Se o app estiver controlando um MediaSession, use um MediaControllerAdapter para chamar um dos métodos MediaControllerCompat.TransportControls mostrados na tabela. Os botões de seleção funcionam como botões "Play" ou "Pause" nesse contexto.

KeyEventChamada TransportControlsComportamento
BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER e KEYCODE_NUMPAD_ENTER play()Reproduzir
BUTTON_START, BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER e KEYCODE_NUMPAD_ENTER pause()Pausar
BUTTON_R1skipToNext()Pular para o próximo
BUTTON_L1skipToPrevious()Pular para a anterior
DPAD_RIGHT, BUTTON_R2, AXIS_RTRIGGER, AXIS_THROTTLEfastForward()Avançar
DPAD_LEFT, BUTTON_L2, AXIS_LTRIGGER, AXIS_BRAKErewind()Voltar
N/Astop()Parar

Observação:ao usar um MediaSession, não modifique o gerenciamento de botões específicos de mídia, como KEYCODE_MEDIA_PLAY ou KEYCODE_MEDIA_PAUSE. O sistema aciona automaticamente o método MediaSession.Callback apropriado.

Fornecer o comportamento adequado do botão "Voltar"

O botão "Voltar" nunca deve funcionar como um botão de alternância. Por exemplo, não o use para abrir e fechar um menu ao mesmo tempo. Use-a apenas para navegar para trás, no estilo de navegação estrutural, pelas telas anteriores em que o jogador esteve.

Como o botão "Voltar" executa apenas a navegação linear e para trás, você pode usá-lo para deixar um menu no app aberto por um botão diferente e retornar ao app. O pressionamento do botão "Voltar" consecutivamente sempre precisa levar à tela inicial do Android TV. Por exemplo: reprodução de jogo > tela de pausa de jogo > tela principal do jogo > tela inicial do Android TV ou exibição de programa de TV > tela principal do app de TV > tela inicial do Android TV.

Para mais informações sobre o design para navegação, consulte Como projetar uma navegação de retorno e para cima. Para saber mais sobre a implementação, consulte Como fornecer uma navegação de retorno adequada.

Gerenciar controladores para jogos

Compatibilidade com controles D-pad

Planeje seu esquema de controle em torno de um controle direcional, já que esse conjunto de controles é o padrão para dispositivos Android TV. O jogador precisa ser capaz de usar um botão direcional para todos os aspectos do jogo, não apenas para controlar a jogabilidade principal, mas também para navegar nos menus e anúncios. Por esse motivo, seu jogo para Android TV não pode se referir a uma interface de toque com linguagem como "Toque aqui para continuar".

A forma como você molda a interação do jogador com o controle pode ser fundamental para proporcionar uma ótima experiência do usuário. Considere as seguintes práticas recomendadas:

  • Comunicar os requisitos dos controles com antecedência:use sua descrição do Google Play para informar ao jogador todas as expectativas sobre os controles. Se um jogo é mais adequado para um gamepad com joystick do que um com apenas um botão direcional, deixe isso claro. Um jogador que usa um controle inadequado para um jogo pode ter uma experiência ruim e uma classificação ruim do jogo.
  • Use mapeamento de botões consistente:o mapeamento intuitivo é fundamental para uma boa experiência do usuário. Por exemplo, siga os costumes aceitos usando o botão A para aceitar e o botão B para cancelar. Você também pode oferecer flexibilidade na forma de remapeamento. Para mais informações sobre o mapeamento de botões, consulte Gerenciar ações do controlador.
  • Detecte os recursos do controle e faça os ajustes necessários:consulte o controlador sobre os recursos dele para otimizar a correspondência entre o controle e o jogo. Por exemplo, você pode querer que o jogador direcione um objeto balançando o controle no ar, mas se o controle do jogador não tiver o hardware do acelerômetro e do giroscópio, acenar não funcionará. Consulte o controlador e, se a detecção de movimento não for compatível, mude para um esquema de controle alternativo disponível. Para mais informações sobre como consultar os recursos do controlador, consulte Suporte a controladores em várias versões do Android.

Usar os botões apropriados

Nem todos os controladores de jogos oferecem os botões "Iniciar", "Pesquisar" ou "Menu". Confira se a interface não depende do uso desses botões.

Gerenciar vários controles

Quando vários jogadores estão jogando, cada um com o próprio controle, é importante mapear cada par de jogador/controlador. Para mais informações sobre como implementar a identificação de número do controlador, consulte getControllerNumber().

Tratar desconexões do controlador

Quando um controle for desconectado no meio do jogo, pause o jogo e mostre uma caixa de diálogo solicitando que o jogador desconectado reconecte o controle.

Além disso, ofereça dicas de solução de problemas na caixa de diálogo. Por exemplo, diga ao player para "Verifique sua conexão Bluetooth". Para ver mais informações sobre como implementar a compatibilidade com dispositivos de entrada, consulte Gerenciar ações do controlador e a Visão geral do Bluetooth.

Mostrar instruções de controladores

Se seu jogo fornece instruções visuais de controle, use uma imagem do controle sem marcas e inclua apenas botões compatíveis com Android.

Para ver exemplos de imagens de um controle compatível com Android, faça o download do Modelo de gamepad do Android TV (ZIP). Ele inclui um controle branco sobre um fundo preto e um controle preto em um fundo branco (mostrado na Figura 1) como um arquivo PNG e como um arquivo do Adobe® Illustrator®.

Figura 1. Exemplo de instruções de controle usando o modelo de gamepad do Android TV.