Introdução a apps para TV

Os apps para TV usam a mesma estrutura dos apps para smartphones e tablets. Essa semelhança significa que você pode modificar os apps existentes para que também sejam executados em dispositivos de TV ou criar novos com base no que 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 saber mais sobre como criar apps para TV, consulte Projetar para TV. Consulte também os apps de exemplo 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 com suporte do Android TV:

• Formatos de mídia compatíveis
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

Configurar um projeto para TV

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

Observação:recomendamos que você tenha um único app compatível com dispositivos móveis e de TV. Se você precisar de apps separados para dispositivos móveis e de TV, poderá publicar vários apps na mesma página de detalhes no Google Play usando a compatibilidade com vários APKs. Para mais informações, consulte Suporte a vários APKs.

Declarar uma atividade para TV

Um aplicativo destinado a ser executado em dispositivos de TV precisa declarar uma atividade de tela de início para TV no manifesto. Ele usa um filtro de intent CATEGORY_LEANBACK_LAUNCHER para fazer isso. Esse filtro identifica seu app como ativado para TV e permite que o Google Play o identifique como um app de TV. Quando um usuário seleciona seu app na tela inicial da TV, esse intent identifica qual atividade será iniciada.

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 essa é 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 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 app para TV ou a parte para TV do app existente precisa oferecer uma interface simples para facilitar a navegação usando um controle remoto a 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 smartphones e tablets. Para orientações sobre como projetar um app para TV, consulte Projetar para TV. Para mais informações sobre os requisitos mínimos de implementação para layouts de interface em TVs, consulte Criar layouts para TV.

Declarar suporte ao dispositivo de TV

Declare que seu app é criado para Android TV declarando o recurso android.software.leanback.

Caso seu app seja executado em dispositivos móveis e na TV, defina o valor do atributo required como false. Se você definir o valor do atributo required como true, o Google Play só vai disponibilizar seu app no SO do Android TV.

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

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

Os aplicativos destinados à execução em dispositivos de TV não dependem de telas touchscreen para entrada. Para deixar isso claro, o manifesto do seu 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>

Atenção: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, ele não aparecerá no Google Play em dispositivos de TV.

Fornecer um ícone e um banner de tela inicial

Os apps para 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 são usados como o 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 para Android, precisam ter um ícone de tela inicial. Para conferir as práticas recomendadas sobre como criar um ótimo ponto de partida para seu app e requisitos detalhados de recursos, consulte as diretrizes de ícones e banner do app para Android TV.

Banner da tela inicial

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 para 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, será necessário fornecer versões separadas do banner com texto para cada idioma compatível.

Alterar a cor da tela de início

Cuidado:no Android 12 e em versões mais recentes, as animações de tela de apresentação personalizadas criadas com a API da plataforma SplashScreen não são compatíveis com apps para Android TV.

Quando um app para TV é iniciado, o sistema mostra uma animação semelhante a um círculo preenchido e expansível. 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 snippet a seguir 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 mais informações sobre como trabalhar com temas e estilos, consulte Estilos e temas.

Criar um app para o SO do Android TV

A maioria das bibliotecas do AndroidX pode ser usada com o Android TV. Use componentes de arquitetura, como ViewModel, para gerenciar dados de interface com reconhecimento de ciclo de vida e Room para integrar a bancos de dados SQLite locais da mesma forma que você faria para dispositivos móveis.

A maioria das bibliotecas do AndroidX é compatível com o Android TV. Os apps para TV podem usar os mesmos componentes de arquitetura que os apps para dispositivos móveis. É possível até compartilhar componentes entre formatos. Assim, você só precisa especializar a lógica de apresentação do app para TV.

Compose para TV

Use o Jetpack Compose para criar a interface do SO para TV. O Compose é o app Android moderno para desenvolvimento de interfaces. Além das principais bibliotecas do Compose, as bibliotecas do Compose para TV oferecem componentes dedicados projetados especialmente para a tela grande:

• androidx.tv.foundation
• androidx.tv.material

Descubra como criar um app de TV usando o Compose para TV em Usar o Jetpack Compose no Android TV.

Kit de ferramentas de interface do Leanback (não recomendado)

Historicamente, o kit de ferramentas de interface do Leanback oferece APIs e widgets de interface do usuário exclusivamente para dispositivos de TV usando visualizações e fragmentos do Android:

• androidx.leanback.app
• androidx.leanback.database
• androidx.leanback.graphics
• androidx.leanback.media
• androidx.leanback.preference
• androidx.leanback.system
• androidx.leanback.widget
• androidx.leanback.widget.picker

Descubra como criar um app de TV usando o kit de ferramentas de interface do YouTube Leanback em Como usar o kit de ferramentas de interface do Leanback.

Executar apps para TV

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

Executar em um dispositivo físico

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 até Criar e selecione Criar várias vezes até receber a mensagem "Agora você é 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 seu 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 no SDK do Android oferece definições de dispositivos que permitem criar dispositivos de TV virtuais para executar e testar seus aplicativos.

Para criar um dispositivo de TV virtual:

1. Inicie o AVD Manager. Para mais informações, consulte 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 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 disponível. Para saber mais sobre a aceleração de hardware do emulador, consulte Configurar a aceleração de hardware para o Android Emulator.

Para testar o aplicativo no dispositivo de TV virtual:

1. No Android Studio, selecione seu 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 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 app para TV e podem ajudar a aumentar a adoção.

Para configurar um 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, na intent-filter do MainActivity do app para TV, verifique 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>

O app para 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 saiba quais são as próximas etapas para preparar seu app para TV para publicação e distribuição.