Criar e executar um app de TV

Os apps para TV têm a mesma estrutura dos apps para smartphones e tablets. Essa semelhança significa que você pode modificar os apps existentes para execução também 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 de TV.

Este guia descreve como preparar o 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 informações sobre como projetar apps para TV, consulte Design for 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 a seguir para ter informações sobre codecs, protocolos e formatos compatíveis com o 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, seja modificando um app Android existente para execução em dispositivos de TV ou criando um novo app de TV. Se você já tem um app Android, o acréscimo de compatibilidade com o Android TV permite que você crie uma interface do usuário para TV aproveitando a arquitetura do seu app.

Observação: recomendamos que você tenha um único app compatível com dispositivos móveis e de TV. Se você precisa de apps separados para dispositivos móveis e de TV dispositivos, pode publicar vários apps na mesma lista do Google Play por meio da compatibilidade com vários APKs. Para mais informações, consulte Compatibilidade com vários APKs.

Há dois componentes principais usados ao criar um app que é executado em dispositivos de TV:

• Atividade para TV: no manifesto do aplicativo, declare uma atividade prevista para execução em dispositivos de TV.
• Bibliotecas de TV: opcionalmente, inclua uma ou mais bibliotecas androidx disponíveis para dispositivos de TV, que estão listadas em outra seção deste guia. Essas bibliotecas oferecem 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.
• Atualize o SDK com o Android 5.0 (API 21) ou mais recente.
  A versão atualizada da plataforma oferece novas APIs para apps de 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 app previsto para execução em dispositivos de TV precisa declarar uma atividade de tela de início para TV no manifesto. Para fazer isso, ele usa um CATEGORY_LEANBACK_LAUNCHER filtro de intent. 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 selecionar seu app na tela de início da TV, esse intent identificará a atividade a 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 a atividade a ser iniciada em um dispositivo de TV.

Cuidado:se você não incluir o filtro de intent CATEGORY_LEANBACK_LAUNCHER no seu 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 de desenvolvedor para carregá-lo em um dispositivo de TV, o app não 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 navegação intuitiva usando um controle remoto a 3 metros de distância. Se estiver modificando um app existente para uso na TV, não use o mesmo layout de atividade que usa em smartphones e tablets. Para orientações sobre como projetar um app para TV, consulte Projetar para TV.

Declarar suporte a dispositivos de TV

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

Se o app for executado em dispositivos móveis e de 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 Android TV.

<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 de toque para entradas. Para deixar isso claro, o manifesto do seu app para TV precisa declarar que o android.hardware.touchscreen recurso não é necessário. Essa configuração identifica o app como capaz de funcionar em um dispositivo de TV e é necessária para que ele seja considerado um app de 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:é preciso declarar que uma tela de toque não é necessária no manifesto do seu app, como mostrado nesse código de exemplo. Caso contrário, o app não vai aparecer no Google Play em dispositivos de TV.

Fornecer um ícone e um banner da tela inicial

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

Para adicionar esses itens ao app, descreva o ícone e o banner no manifesto desta forma:

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

Ícone da tela inicial

Os apps para Android TV, como todos os apps Android, precisam fornecer um ícone da tela inicial. Para conferir as práticas recomendadas sobre como projetar um ótimo ponto de inicialização para seu app e os requisitos detalhados de recursos, consulte as diretrizes de ícones e banners de apps para Android TV.

Banner da tela inicial

Use o android:banner atributo com a <application> tag para fornecer um banner padrão para todas as atividades do aplicativo ou com a <activity> tag 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 seu app estiver disponível em mais de um idioma, você precisará fornecer versões diferentes do banner com texto para cada idioma.

Alterar a cor da tela de início

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

Quando um app de TV é inicializado, o sistema exibe uma animação parecida com um círculo preenchido se expandindo. Para personalizar a cor dessa animação, configure o atributo android:colorPrimary do seu app de TV ou atividade para uma cor específica. Além disso, defina dois atributos de sobreposição de transição como true, conforme mostrado no snippet de um arquivo XML de recursos de tema a seguir:

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

Para mais informações sobre como trabalhar com temas e estilos, consulte Estilos e temas.

Criar um app para o SO Android TV

O Jetpack inclui bibliotecas de pacotes androidx para uso em apps para TV.

Compose para TV

O Compose é a maneira recomendada de criar apps para o SO Android TV. 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

O kit de ferramentas de interface do Leanback oferece APIs e widgets de interface do usuário para dispositivos de TV:

• 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 Leanback em Criar apps de reprodução para TV.

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.
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 do Android SDK oferece definições de dispositivo 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 melhor desempenho do emulador de dispositivo de TV, use o emulador x86 e ative a opção Use Host GPU. Use também a aceleração de dispositivo virtual, se disponível. Para mais informações 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 seu dispositivo de TV virtual e clique em OK.

Para mais informações 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.

Ativar a execução do app de TV como uma experiência instantânea

As experiências instantâneas permitem que os usuários testem seu app de TV sem instalá-lo e podem ajudar a aumentar a adoção.

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

Em seguida, no intent-filter do seu app para TV MainActivity, 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>

Seu app de TV agora está configurado para execução como uma experiência instantânea.

Preparar o app de TV para publicação

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