Introdução a apps para TV

Os apps para TV têm a mesma estrutura que os apps para smartphones e tablets. Essa semelhança significa que é possível modificar os apps existentes para execução em dispositivos de TV ou criar novos com base no que você já sabe sobre a criação de apps para Android.

Importante:seu app precisa atender a requisitos específicos para se qualificar como um app para Android TV no Google Play. Para mais informações, consulte os requisitos listados em Qualidade do app para TV.

Este guia descreve como preparar seu ambiente de desenvolvimento para a criação de apps para TV e as mudanças mínimas necessárias para permitir que um app seja executado em dispositivos de TV.

Para mais informações sobre como projetar apps para TV, consulte Projetar para TV e Criar layouts para TV. Para analisar um app de TV de exemplo, consulte o app de exemplo de Leanback do Android no repositório do GitHub para Android TV (link em inglês).

Determinar a compatibilidade com formatos de mídia

Consulte a documentação abaixo para mais informações sobre codecs, protocolos e formatos compatíveis com o Android TV:

Configurar um projeto para TV

Esta seção discute como configurar um projeto para TV, seja modificando um app Android existente para que ele seja executado em dispositivos de TV ou criando um novo. Se você já tiver um app Android, adicionar compatibilidade com o Android TV permite criar uma interface do usuário para TV reutilizando a arquitetura do app.

Dois componentes principais são usados ao criar um app para execução em dispositivos de TV:

  • Atividade para TV:no manifesto do aplicativo, declare uma atividade destinada à execução em dispositivos de TV.
  • Bibliotecas de TV:como opção, inclua uma ou mais das bibliotecas androidx disponíveis para dispositivos de TV, que estão listadas em outra seção deste guia. Essas bibliotecas fornecem widgets para a criação de interfaces do usuário.

Pré-requisitos

Antes de começar a criar um app para TV, siga estas etapas:

  • Atualize as ferramentas do SDK para a versão 24.0.0 ou mais recente.
    As Ferramentas do SDK atualizadas permitem criar e testar apps para TV.
  • Atualizar o SDK com o Android 5.0 (nível 21 da API) ou mais recente.
    A versão atualizada da plataforma oferece novas APIs para apps para TV.
  • Crie ou atualize o projeto do app.
    Para acessar novas APIs para dispositivos de TV, crie um projeto ou modifique um projeto existente direcionado ao Android 5.0 (nível 21 da API) ou mais recente.

Declarar uma atividade para TV

Um aplicativo destinado à execução em dispositivos de TV precisa declarar uma atividade de tela de início para TV no manifesto. Para isso, ele usa um filtro de intent CATEGORY_LEANBACK_LAUNCHER. Esse filtro identifica seu app como ativado para TV e permite que o Google Play o identifique como um app para TV. Quando um usuário seleciona seu app na tela inicial da TV, essa intent identifica qual atividade iniciar.

O snippet de código a seguir mostra como incluir esse filtro de intent no manifesto:

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

A segunda entrada no manifesto de atividades deste exemplo especifica que é a atividade a ser iniciada em um dispositivo de TV.

Cuidado:se você não incluir o filtro de intent CATEGORY_LEANBACK_LAUNCHER no app, ele não ficará visível para os usuários que estiverem executando o Google Play em dispositivos de TV. Além disso, se o app não tiver esse filtro quando você usar as ferramentas para desenvolvedores para carregá-lo em um dispositivo de TV, ele não vai aparecer na interface do usuário da TV.

A interface do usuário do seu app para TV (ou a parte de TV do app existente) precisa fornecer uma interface simples para facilitar a navegação usando um controle remoto de três metros de distância. Se você estiver modificando um app existente para uso na TV, não use o mesmo layout de atividade para TVs que você usa para smartphones e tablets. Para diretrizes sobre como projetar um app para TV, consulte Como projetar para TV. Para saber mais sobre os requisitos mínimos de implementação para layouts de interface em TVs, consulte Criar layouts para TV.

Declarar compatibilidade com Leanback

Declare que seu app usa a interface do usuário do YouTube Leanback exigida pelo Android TV. Caso seu app seja executado em dispositivos móveis e também no Android TV, defina o valor do atributo required como false. Se você definir o valor do atributo required como true, o app só poderá ser executado em dispositivos que usam a interface do Leanback.

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

Não é necessário declarar a tela de toque

Aplicativos destinados à execução em dispositivos de TV não dependem de telas touchscreen para entrada. Para deixar isso claro, o manifesto do app para TV precisa declarar que o recurso android.hardware.touchscreen não é necessário. Essa configuração identifica seu app como capaz de funcionar em um dispositivo de TV e é necessária para que ele seja considerado um app para TV no Google Play. O exemplo de código a seguir mostra como incluir essa declaração no manifesto:

<manifest>
    <uses-feature android:name="android.hardware.touchscreen"
              android:required="false" />
    ...
</manifest>

Cuidado:no manifesto do app, é necessário declarar que uma tela touchscreen não é necessária, conforme mostrado neste código de exemplo. Caso contrário, o app não aparecerá no Google Play em dispositivos de TV.

Fornecer um ícone e um banner de tela inicial

Os apps do Android TV precisam fornecer um ícone de tela inicial e uma imagem de banner para cada localização. Dependendo do dispositivo Android TV, o ícone ou o banner é usado como ponto de inicialização do app que aparece na tela inicial nas linhas de apps e jogos.

Para adicioná-los ao seu app, descreva o ícone e o banner no manifesto da seguinte maneira:

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

Ícone da tela inicial

Os apps do Android TV, como todos os apps Android, precisam oferecer um ícone de tela inicial. Para conferir as práticas recomendadas sobre como criar um ótimo ponto de lançamento para seu app e conferir os requisitos detalhados dos recursos, consulte as diretrizes de banner e para ícones do app Android TV.

Use o atributo android:banner com a tag <application> para fornecer um banner padrão a todas as atividades do aplicativo ou com a tag <activity> para fornecer um banner a uma atividade específica.

Para o banner, use um recurso xhdpi com tamanho de 320 x 180 px. O texto precisa ser incluído na imagem. Se o app estiver disponível em mais de um idioma, forneça versões separadas do banner com texto para cada um deles.

Alterar a cor da tela de início

Cuidado:no Android 12 e versões mais recentes, as animações de tela de apresentação personalizadas criadas usando a API da plataforma SplashScreen não oferecem suporte a apps do Android TV.

Quando um app de TV é iniciado, o sistema exibe uma animação que se assemelha a um círculo preenchido e em expansão. Para personalizar a cor dessa animação, defina o atributo android:colorPrimary do app ou da atividade para TV como uma cor específica. Além disso, defina dois atributos de sobreposição de transição como true, conforme mostrado no seguinte snippet de um arquivo XML de recursos de tema:

<resources>
    <style ... >
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>

Para saber mais sobre como trabalhar com temas e estilos, consulte Estilos e temas.

Adicionar bibliotecas de TV

O Jetpack inclui bibliotecas de pacotes androidx para uso em apps para TV. Essas bibliotecas oferecem APIs e widgets de interface do usuário para dispositivos de TV:

Criar apps para TV

Depois de concluir as etapas listadas anteriormente, é hora de começar a criar apps para a tela grande. Confira estes tópicos adicionais para ajudar a criar o aplicativo para TV:

  • Criar apps de reprodução para TV: as TVs são criadas para entreter. Por isso, o Android oferece ferramentas e widgets de interface do usuário para a criação de apps para TV que reproduzam vídeos e música e permitam que os usuários procurem o conteúdo que querem.
  • Ajudar os usuários a encontrar seu conteúdo no Android TV: com todas as opções de conteúdo ao alcance dos usuários, ajudar a encontrar conteúdo de que eles gostem é quase tão importante quanto oferecer esse conteúdo. Este guia discute como exibir o conteúdo em dispositivos de TV.
  • Criar jogos para TV: dispositivos de TV são uma ótima plataforma para jogos. Consulte este tópico para ter informações sobre como criar incríveis experiências de jogos para TV.
  • Criar serviços de entrada para TV: apresente seu conteúdo de vídeo de maneira linear, no estilo de uma transmissão de TV, com canais e programas que os usuários podem acessar por meio do guia de programas e dos botões de canal para cima ou para baixo.

Executar apps para TV

A execução do app é parte importante do processo de desenvolvimento. É possível executar o app em dispositivos de TV compatíveis com a depuração USB ou usar dispositivos de TV virtual.

Executar em um dispositivo real

Configure a TV da seguinte maneira:

  1. Use um cabo USB para conectar seu dispositivo de TV a sua máquina de desenvolvimento. Se necessário, consulte a documentação fornecida pelo fabricante do dispositivo.
  2. No dispositivo de TV, navegue até Configurações.
  3. Na linha Dispositivo, selecione Sobre.
  4. Role para baixo até Criar e selecione Criar várias vezes até receber a mensagem "Você agora é um desenvolvedor."
  5. Volte para Configurações. Na linha Preferências, selecione Opções do desenvolvedor.
  6. Selecione Depuração > Depuração USB e selecione Ativado.
  7. Volte para a tela inicial da TV.

Para testar seu aplicativo no dispositivo de TV:

  1. No Android Studio, selecione o projeto e clique em Run na barra de ferramentas.
  2. Na janela Select Deployment Target, selecione seu dispositivo de TV e clique em OK.

Executar em um dispositivo virtual

O AVD Manager do Android SDK oferece definições de dispositivos que permitem criar dispositivos de TV virtuais para executar e testar seus apps.

Para criar um dispositivo de TV virtual:

  1. Inicie o AVD Manager. Para mais informações, acesse Criar e gerenciar dispositivos virtuais.
  2. Na caixa de diálogo do AVD Manager, clique na guia Device Definitions.
  3. Selecione uma das definições de dispositivo do Android TV e clique em Create AVD.
  4. Selecione as opções do emulador e clique em OK para criar o AVD.

    Observação:para conseguir o melhor desempenho do dispositivo emulador de TV, use o emulador x86 e ative a opção Use Host GPU. Use também a aceleração de dispositivo virtual quando ela estiver disponível. Para saber mais sobre a aceleração de hardware do emulador, consulte Configurar aceleração de hardware para o Android Emulator.

Para testar o aplicativo no dispositivo de TV virtual:

  1. No Android Studio, selecione o projeto e clique em Run na barra de ferramentas.
  2. Na janela Select Deployment Target, selecione o dispositivo de TV virtual e clique em OK.

Para saber mais sobre o uso de emuladores, consulte Executar apps no Android Emulator. Para ver mais informações sobre a implantação de apps do Android Studio em dispositivos virtuais, consulte Depurar seu app.

Permitir que seu app de TV seja executado como uma experiência instantânea

As experiências instantâneas facilitam o teste do seu app para TV e ajudam a aumentar a adoção.

Para configurar seu app de TV para ser executado como um app instantâneo em um emulador ou dispositivo Android TV, primeiro siga as instruções para criar um pacote de apps instantâneos.

Em seguida, no intent-filter do MainActivity do app para TV, confira se LAUNCHER e LEANBACK_LAUNCHER estão declarados em 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>

Seu app de TV agora está configurado para ser executado como uma experiência instantânea.

Preparar seu app de TV para publicação

Consulte a lista de verificação de apps para TV e confira as próximas etapas para preparar seu app de TV para publicação e distribuição.