Gerenciar controles de TV

Os dispositivos de TV exigem um hardware secundário para interagir com apps: um controle remoto básico, um controle remoto com ponteiro ou um controle de jogos. Para oferecer uma experiência consistente ao usuário, seu app precisa oferecer suporte à entrada por botão direcional (D-pad), lidar com controladores que ficam off-line e oferecer suporte à entrada de vários tipos de controladores, incluindo controles remotos com ponteiro.

Controles D-pad mínimos

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

Para mais informações sobre a navegação com botões direcionais para dispositivos de TV, consulte Navegação na TV.

Tratar desconexões do controlador

Os controles de TV geralmente são dispositivos Bluetooth, que podem tentar economizar energia entrando periodicamente no modo de espera e se desconectando do dispositivo de TV. Isso significa que um app pode 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:

• Enquanto um vídeo de vários minutos é reproduzido, um botão direcional ou um controle de jogo pode entrar no modo de espera, desconectar-se do dispositivo de TV e se reconectar mais tarde.
• Durante o jogo, um novo jogador pode entrar usando um controle de jogo que ainda não está conectado.
• Durante o jogo, um jogador pode sair e desconectar um controle.

Toda 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 ativar uma atividade para processar mudanças de configuração, incluindo a conexão, desconexão ou reconexão de um teclado ou dispositivo de navegação:

<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 sendo executado durante 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 controle básico com botão direcional, um controle remoto com ponteiro ou um controle de jogos. Os códigos de tecla fornecidos por um controle de jogo quando ele é usado para funções de botão direcional podem variar dos códigos de tecla enviados por um botão direcional básico.

Gerencie as variações na entrada por botão direcional para que o usuário não precise trocar de controles para operar seu app. Para mais informações sobre como gerenciar variações de entrada, consulte Processar entrada por botão direcional.

Suporte a controles remotos com ponteiro

Alguns dispositivos de TV são compatíveis com controles remotos com ponteiro, como air mice ou controles com pads direcionais sensíveis ao toque (trackpads). Com suporte a controles remotos com ponteiro, os usuários podem interagir com seu app usando gestos de apontar e clicar, passar o cursor, deslizar e arrastar, proporcionando uma experiência mais fluida em hardware compatível e mantendo a compatibilidade total com o botão direcional.

Declarar suporte remoto a ponteiro no manifesto

Para indicar que o app pode ser navegado com entrada de ponteiro e toque, configure o manifesto do app com o conjunto de metadados android.software.leanback.supports_touch definido como 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>

Compatibilidade com interações de clique, passar o cursor e rolar a tela

Ao oferecer suporte a controles remotos com ponteiro, verifique se os componentes da interface respondem adequadamente à entrada de toque e cursor nas seguintes interações:

• Clique e seleção:todos os elementos da interface focalizáveis e selecionáveis precisam ser clicáveis com o controle remoto apontador, correspondendo ao comportamento da seleção com o botão direcional (KEYCODE_DPAD_CENTER).
  • Jetpack Compose:use os modificadores Modifier.clickable() ou pointerInput. Para mais detalhes, consulte Tocar e pressionar.
  • Visualizações:processam eventos de clique nas visualizações. Para mais detalhes, consulte a Visão geral dos eventos de entrada.
• Estados visuais de passar o cursor:oferecem um efeito visual claro para indicar quando o cursor do ponteiro está posicionado sobre um item selecionável.
  • Jetpack Compose:use Modifier.hoverable() ou observe estados de passar o cursor usando um InteractionSource. Para mais detalhes, consulte Processar interações do usuário.
  • Visualizações:defina estados de passar o cursor usando drawables de lista de estados com android:state_hovered="true".
• Rolagem por deslizar e deslizar rapidamente:a rolagem horizontal e vertical acionada por um gesto de deslizar ou deslizar rapidamente em um botão direcional central sensível ao toque precisa funcionar sem problemas em todo o conteúdo rolável.
• Rolagem por arrastar:os usuários precisam conseguir arrastar para rolar verticalmente (para cima e para baixo) ou horizontalmente (para a esquerda e direita) em contêineres roláveis.
  • Jetpack Compose:os contêineres roláveis padrão são compatíveis com rolagem por toque e ponteiro por padrão. Para implementações personalizadas, consulte Entrada de ponteiro no Compose.
  • Visualizações:as visualizações roláveis padrão oferecem suporte à rolagem por toque por padrão. Para processamento de entrada personalizado, consulte Toque e entrada.
• Limpeza da reprodução de mídia:durante a reprodução de mídia (como programas de TV e filmes), os usuários precisam conseguir interagir com a barra de progresso da reprodução (barra de busca) apontando e clicando para pular para um carimbo de data/hora passado ou futuro, além de arrastar (limpar) ao longo da barra de progresso para buscar um horário específico.

Gerenciar eventos de botão

Quando o usuário clica em um botão de um controle, 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 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 do controle.

Eventos de IU da TV

Atribua o comportamento da interface da TV aos botões que geram tipos KeyEvent, conforme mostrado na tabela a seguir:

Eventos de mídia

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

Fornecer um comportamento adequado para o botão "Voltar"

O botão "Voltar" nunca deve funcionar como uma alternância. Por exemplo, não use para abrir e fechar um menu. Use apenas para navegar para trás, no estilo breadcrumb, pelas telas anteriores em que o player esteve.

Como o botão "Voltar" só realiza navegação linear para trás, você pode usá-lo para sair de um menu no app aberto por outro botão e voltar ao app. Pressionar o botão "Voltar" consecutivamente sempre leva à tela inicial do Android TV. Por exemplo: jogo > tela de pausa do jogo > tela principal do jogo > tela inicial do Android TV ou programa de TV > tela principal do app de TV

Tela inicial do Android TV.

Para mais informações sobre design para navegação, consulte Como criar navegação para voltar e subir. Para saber mais sobre a implementação, consulte Oferecer navegação de retorno adequada.

Gerenciar controladores para jogos

Ao criar jogos para o Android TV, crie um esquema de controle que funcione com controles remotos de TV padrão e controles de jogos dedicados.

Compatibilidade com controles D-pad

Planeje seu esquema de controle com base em um controle de botão direcional, já que esse conjunto de controles é o padrão para dispositivos Android TV. O jogador precisa conseguir usar um botão direcional para todos os aspectos do jogo, não apenas para controlar a jogabilidade principal, mas também navegar por menus e anúncios. Por isso, confira se o jogo para Android TV não se refere 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 conseguir uma ótima experiência do usuário. Considere as práticas recomendadas a seguir:

• Comunique os requisitos do controle com antecedência:use a descrição do Google Play para informar ao jogador as expectativas sobre os controles. Se um jogo for mais adequado para um gamepad com um 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 dar uma classificação baixa ao jogo.
• Use um mapeamento de botões consistente:um 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 permitindo que o usuário remapeie os botões. Para mais informações sobre o mapeamento de botões, consulte Processar ações do controlador.
• Detectar recursos do controle e ajustar de acordo:consulte o controle sobre os recursos dele para otimizar a correspondência entre o controle e o jogo. Por exemplo, você pode querer que um jogador mova um objeto acenando o controle no ar, mas se o controle de um jogador não tiver hardware de acelerômetro e giroscópio, acenar não vai 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 recursos do controlador, consulte Compatibilidade com controles em diversas versões do Android.

Usar os botões apropriados

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

Gerenciar vários controles

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

Tratar desconexões do controlador

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

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

Mostrar instruções de controladores

Se o jogo fornecer instruções visuais de controle, use uma imagem de controle sem marca e inclua apenas botões compatíveis com o 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 em um fundo preto e um controle preto em um fundo branco, mostrados na figura 1, como um arquivo PNG e um arquivo do Adobe® Illustrator®.