Criar e executar um app de TV

Os apps para TV usam a mesma estrutura dos apps para smartphones e tablets. Essa semelhança significa que é possível modifique seus apps atuais para que também sejam executados em dispositivos de TV ou crie novos apps com base no que você já sobre a criação de aplicativos 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 na qualidade de apps para 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 mais informações sobre como criar aplicativos para TV, consulte Projetar para TV. Confira também os apps de exemplo na Repositório GitHub do Android TV (link em inglês).

Determinar a compatibilidade com formatos de mídia

Consulte a documentação a seguir para mais informações sobre codecs, protocolos e formatos com suporte no 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ê a modificação de um app Android para execução em dispositivos de TV ou a criação de um novo app de TV. Se você já tem um app Android, adicionar o suporte ao Android TV permite projetar uma interface do usuário para TV, reutilizando a arquitetura do app atual.

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

Há dois componentes principais usados ao criar um app para execução em dispositivos de TV:

• Atividade para TV:no manifesto do app, declarar uma atividade destinada a ser executada 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 listados 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.
• 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 existente voltado ao Android 5.0 (nível 21 da API) ou versões mais recentes.

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. Ela usa uma intent CATEGORY_LEANBACK_LAUNCHER. para fazer isso. Esse filtro identifica seu aplicativo como ativado para TV e permite o Google Play o identificou como um app de 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 do manifesto de atividade neste exemplo especifica que é a atividade a ser iniciar em um dispositivo de TV.

Atenção: se você não incluir o CATEGORY_LEANBACK_LAUNCHER filtro de intent em o app, ele não ficará visível para os usuários que executam o Google Play em dispositivos de TV. Além disso, se sua não tem esse filtro quando você usa ferramentas para desenvolvedores para carregá-lo em uma TV, o app não aparece na interface do usuário da TV.

A interface do usuário do seu 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 para uso na TV, não use o mesmo layout de atividade para a TV que você usa em smartphones e tablets. Para orientações sobre como criar um app para TV, consulte Projetar para TV.

Declarar suporte ao dispositivo de TV

Declare que seu app é criado para Android TV declarando a 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ó disponibilizará o 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 de TV precisa declarar que os O recurso android.hardware.touchscreen não é necessário. Essa configuração identifica seu app como funcionar em um dispositivo de TV, e é necessário para que o app seja considerado um app de TV no Google. 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 a tela touchscreen não é necessária. como mostrado neste exemplo de código. Caso contrário, o app não aparecerá no Google Play na TV. dispositivos.

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 quando o app é iniciado. 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 práticas recomendadas um ótimo ponto de partida para seu app e requisitos detalhados de recursos, consulte o Ícone e banner do app Android TV diretrizes.

Banner da tela inicial

Usar o android:banner com o atributo <application> , para fornecer um banner padrão para 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 deve ser incluído no imagem. Caso seu app esteja disponível em mais de um idioma, forneça versões separadas do banner com texto para cada idioma aceito.

Alterar a cor da tela de início

Cuidado:no Android 12 e versões mais recentes, animações de tela de apresentação personalizadas criadas usando o A API da plataforma SplashScreen não tem suporte em apps para Android TV.

Quando um aplicativo de TV é iniciado, o sistema exibe uma animação semelhante a uma expansão círculo Para personalizar a cor dessa animação, defina o android:colorPrimary atributo do seu app ou atividade para TV a uma cor específica. Além disso, defina dois atributos de sobreposição de transição para true, conforme mostrado no snippet a seguir de uma 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 obter mais informações sobre como trabalhar com temas e estilos, consulte Estilos e temas.

Criar um app para o SO do 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. Com o Compose principal as bibliotecas do Compose para TV oferecem componentes dedicados projetados especialmente para as 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 no Crie apps de reprodução para TV.

Executar apps para TV

A execução do app é parte importante do processo de desenvolvimento. É possível executar seu app em Dispositivos de TV configurados para oferecer suporte à 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é Build e selecione Build 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 o projeto e clique em Executar na barra de ferramentas.
2. Na janela Select Deployment Target, faça o seguinte: selecione a TV e clique em OK.

Executar em um dispositivo virtual

O AVD Manager no Android O SDK fornece definições de dispositivo que permitem criar dispositivos de TV virtuais para execução e para 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 ter o melhor desempenho do emulador de TV, use o emulador x86. e ative a opção Usar GPU host. Use também a aceleração de dispositivo virtual disponíveis. Para mais informações sobre a aceleração de hardware do emulador, consulte Configure a 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 Executar na barra de ferramentas.
2. Na janela Select Deployment Target, faça o seguinte: selecione o dispositivo de TV virtual e clique em OK.

Para mais informações sobre como usar emuladores, consulte Executar apps no Android Emulator. Para mais informações sobre como implantar apps do Android Studio em aplicativos dispositivos, 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 trabalho dos usuários para testar seu app para TV e pode ajudar a aumentar a adoção.

Se quiser configurar um app para TV para ser executado como um app instantâneo em um emulador ou dispositivo Android TV, faça o seguinte: primeiro siga as instruções para Crie um pacote de apps instantâneos.

Em seguida, no intent-filter do dispositivo MainActivity, verifique se LAUNCHER e LEANBACK_LAUNCHER sã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 para saber as próximas etapas para preparar seu app de TV para publicação e distribuição.