Os apps de TV usam a mesma estrutura dos apps para smartphones e tablets. Essa semelhança significa que você pode modificar os apps atuais para também serem executados em dispositivos de TV ou criar novos apps 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 de TV.
Este guia descreve como preparar seu ambiente de desenvolvimento para criar apps de 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 criar apps para TV, consulte Design para TV. Confira também os apps de exemplo no repositório do Android TV no GitHub (link em inglês).
Determinar a compatibilidade com formatos de mídia
Consulte a documentação a seguir para informações sobre os codecs, protocolos e formatos compatíveis com o Android TV:
Configurar um projeto para TV
Esta seção explica como configurar um projeto de TV, seja modificando um app Android existente para ser executado em dispositivos de TV ou criando um novo app de TV. Se você já tem um app Android, adicionar suporte ao Android TV permite criar uma interface do usuário para TV enquanto reutiliza a arquitetura do app atual.
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 destinada a ser executada em dispositivos de TV.
- Bibliotecas de TV:se quiser, 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 criar interfaces de 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.
Com as ferramentas atualizadas do SDK, você pode 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 ou modifique um projeto que seja destinado ao Android 5.0 (nível 21 da API) ou mais recente.
Declarar uma atividade para TV
Um aplicativo destinado a ser executado em dispositivos de TV precisa declarar uma atividade de inicialização 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, 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 ela é a atividade a ser iniciada em um dispositivo de TV.
Atenção:se você não incluir o filtro de intent
CATEGORY_LEANBACK_LAUNCHER no
app, ele não vai aparecer para usuários que executam 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, ele
não vai aparecer na interface do usuário da TV.
A interface do usuário do app de TV ou a parte de TV do app atual precisa oferecer navegação intuitiva usando um controle remoto a 3 metros de distância. Se você estiver modificando um app para uso na TV, não use o mesmo layout de atividade para TV que usa em smartphones e tablets. Para conferir diretrizes sobre como criar um app para TV, consulte Design para TV.
Declarar suporte a dispositivos de TV
Declare que o app foi criado para o Android TV declarando o
recurso android.software.leanback.
Se o app for executado em dispositivos móveis e TVs, 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 Android TV OS.
<manifest> <uses-feature android:name="android.software.leanback" android:required="false" /> ... </manifest>
Declarar que não é necessário ter uma tela touchscreen
Os aplicativos destinados a dispositivos de TV não dependem de telas touch para entrada.
Para deixar isso claro, o manifesto do app de TV precisa declarar que o recurso
android.hardware.touchscreen não é obrigató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 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>
Atenção:no manifesto do app, declare que uma tela touchscreen não é necessária, como mostrado neste exemplo de código. Caso contrário, o app não vai aparecer no Google Play em dispositivos de TV.
Fornecer um ícone e um banner para a tela inicial
Os apps para Android TV precisam fornecer um ícone da 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 início do app que aparece na tela inicial nas linhas de apps e jogos.
Para adicionar esses elementos ao app, descreva o ícone e o banner no manifesto da seguinte forma:
<application ... android:icon="@mipmap/ic_launcher" android:banner="@drawable/banner" > ... </application>
Ícone da tela inicial
Os apps para Android TV, assim como todos os apps Android, precisam ter um ícone na tela inicial. Para conferir práticas recomendadas sobre como criar um ótimo ponto de partida para seu app e requisitos detalhados de recursos, consulte as diretrizes de ícone 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 a uma atividade específica.
Para o banner, use um recurso xhdpi com tamanho de 320 x 180 px. O texto precisa estar 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 idioma compatível.
Alterar a cor da tela de início
Atenção:no Android 12 e versões mais recentes, animações personalizadas de tela de apresentação criadas usando a
API da plataforma SplashScreen são indisponíveis para apps para Android TV.
Quando um app de TV é iniciado, o sistema mostra uma animação que se parece com um círculo preenchido
em expansão. Para personalizar a cor dessa animação, defina o atributo android:colorPrimary
do app ou da atividade de TV para 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 name="MyTheme"> <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 Android TV OS
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 Android TV OS. Além das bibliotecas principais do Compose, as bibliotecas do Compose para TV oferecem componentes dedicados projetados especialmente para a tela grande:
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 Leanback
O kit de ferramentas de interface do usuário Leanback oferece APIs e widgets de interface do usuário para dispositivos de TV:
androidx.leanback.appandroidx.leanback.databaseandroidx.leanback.graphicsandroidx.leanback.mediaandroidx.leanback.preferenceandroidx.leanback.systemandroidx.leanback.widgetandroidx.leanback.widget.picker
Descubra como criar um app de TV usando o kit de ferramentas Leanback UI 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 o app em dispositivos de TV configurados para oferecer suporte à depuração USB ou usar dispositivos de TV virtuais.
Executar em um dispositivo físico
Configure a TV da seguinte maneira:
- 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.
- No dispositivo de TV, navegue até Configurações.
- Na linha Dispositivo, selecione Sobre.
- Role a tela até Build e selecione Build várias vezes até receber a mensagem "Agora você é um desenvolvedor".
- Volte para Configurações. Na linha Preferências, selecione Opções do desenvolvedor.
- Selecione Depuração > Depuração USB e selecione Ativado.
- Volte para a tela inicial da TV.
Para testar seu aplicativo no dispositivo de TV:
- No Android Studio, selecione seu projeto e clique em
Run
na barra de ferramentas. - Na janela Select Deployment Target, selecione o dispositivo de TV e clique em OK.
Executar em um dispositivo virtual
O AVD Manager no SDK do Android fornece definições de dispositivo que permitem criar dispositivos de TV virtuais para executar e testar seus aplicativos.
Para criar um dispositivo de TV virtual:
- Inicie o AVD Manager. Para mais informações, consulte Criar e gerenciar dispositivos virtuais.
- Na caixa de diálogo do AVD Manager, clique na guia Device Definitions.
- Selecione uma das definições de dispositivo do Android TV e clique em Create AVD.
- Selecione as opções do emulador e clique em OK para criar o AVD.
Observação:para ter o melhor desempenho do dispositivo emulador de TV, use o emulador x86 e ative a opção Usar GPU do host. Também use a aceleração de dispositivo virtual quando ela estiver 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:
- No Android Studio, selecione seu projeto e clique em
Run
na barra de ferramentas.
- 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 como implantar 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
Com as experiências instantâneas, os usuários podem testar seu app de TV sem instalar, o que ajuda a aumentar a adoção.
Para configurar o app de TV para ser executado como um app instantâneo em um dispositivo ou emulador do Android TV, siga as instruções para criar um pacote de app compatível com apps instantâneos.
Em seguida, no intent-filter do
MainActivity do app de 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>
Seu app de TV agora está configurado para ser executado como uma experiência instantânea.
Preparar o app de TV para publicação
Revise a lista de verificação de apps de TV para saber as próximas etapas e preparar seu app de TV para publicação e distribuição.