A tela inicial do Android TV oferece uma interface que mostra o conteúdo recomendado como uma tabela de canais e programas. Cada linha é um canal. Um canal contém cards para cada programa disponível nele:
Este documento demonstra como adicionar canais e programas à tela inicial, atualizar conteúdo, processar ações do usuário e oferecer a melhor experiência para os usuários. Se quiser se aprofundar na API, confira o codelab da tela inicial e assista à sessão do Android TV no I/O 2017.
A IU da tela inicial
Os apps podem criar novos canais, adicionar, remover e atualizar os programas em um canal e controlar a ordem dos programas em um canal. Por exemplo, um app pode criar um canal chamado "Novidades" e mostrar cards de programas recém-disponibilizados.
Os apps não podem controlar a ordem em que os canais aparecem na tela inicial. Quando seu app cria um novo canal, a tela inicial o adiciona à parte de baixo da lista de canais. O usuário pode reordenar, ocultar e mostrar canais.
O canal "Assistir a seguir"
O canal "Assistir a seguir" é a segunda linha que aparece na tela inicial, depois da linha de apps. O sistema cria e mantém esse canal. O app pode adicionar programas ao canal "Assistir a seguir". Para mais informações, consulte Adicionar programas ao canal "Assistir a seguir".
Canais do app
Todos os canais criados pelo app seguem este ciclo de vida:
- O usuário descobre um canal no seu app e solicita que ele seja adicionado à tela inicial.
- O app cria o canal e o adiciona ao
TvProvider(nesse momento, o canal não fica visível). - O app solicita que o sistema exiba o canal.
- O sistema pede que o usuário aprove o novo canal.
- O novo canal aparece na última linha da tela inicial.
O canal padrão
Seu app pode oferecer qualquer número de canais para o usuário adicionar à tela inicial. Normalmente, o usuário precisa selecionar e aprovar cada canal antes que ele apareça na tela inicial. Cada app tem a opção de criar um canal padrão. O canal padrão é especial porque aparece automaticamente na tela inicial. O usuário não precisa solicitá-lo explicitamente.
Pré-requisitos
A tela inicial do Android TV usa as APIs TvProvider do Android para gerenciar os
canais e programas criados pelo app. Para acessar os dados do provedor, adicione
a seguinte permissão ao manifesto do app:
<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
A Biblioteca de Suporte TvProvider facilita o uso do provedor. Adicione-a às
dependências no arquivo build.gradle:
Groovy
implementation 'androidx.tvprovider:tvprovider:1.0.0'
Kotlin
implementation("androidx.tvprovider:tvprovider:1.0.0")
Para trabalhar com canais e programas, inclua estas importações da biblioteca de suporte no seu programa:
import android.support.media.tv.Channel
import android.support.media.tv.TvContractCompat
import android.support.media.tv.ChannelLogoUtils
import android.support.media.tv.PreviewProgram
import android.support.media.tv.WatchNextProgram
Canais
O primeiro canal criado pelo app se torna o canal padrão. O canal padrão aparece automaticamente na tela inicial. Todos os outros canais que você criar precisam ser selecionados e aceitos pelo usuário antes de aparecerem na tela inicial.
Como criar um canal
O app precisa pedir ao sistema para mostrar os canais recém-adicionados somente quando estiver
em execução em primeiro plano. Isso impede que o app mostre uma caixa de diálogo
solicitando aprovação para adicionar seu canal enquanto o usuário está executando um app
diferente. Se você tentar adicionar um canal enquanto estiver em execução em segundo plano, o método
onActivityResult() da atividade vai retornar o código de status RESULT_CANCELED.
Para criar um canal, siga estas etapas:
Crie um gerador de canal e defina os atributos dele. O tipo de canal precisa ser
TYPE_PREVIEW. Adicione mais atributos conforme necessário.val builder = Channel.Builder() // Every channel you create must have the type `TYPE_PREVIEW`. builder.setType(TvContractCompat.Channels.TYPE_PREVIEW) .setDisplayName("Channel Name") .setAppLinkIntentUri(uri)
Insira o canal no provedor:
var channelUri = context.contentResolver.insert( TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues() )
Salve o ID do canal para adicionar programas a ele mais tarde. Extraia o ID do canal do URI retornado:
var channelId = ContentUris.parseId(channelUri)
Você precisa adicionar um logotipo para seu canal. Use um
UriouBitmap. O ícone do logotipo precisa ter 80 x 80 dp e ser opaco. Ela é exibida em uma máscara circular:
// Choose one or the other. storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL. storeChannelLogo(context, channelId, logo)
Criar o canal padrão (opcional): quando o app criar o primeiro canal, você poderá defini-lo como o canal padrão para que ele apareça na tela inicial imediatamente, sem qualquer ação do usuário. Os outros canais que você criar não vão ficar visíveis até que o usuário os selecione explicitamente.
TvContractCompat.requestChannelBrowsable(context, channelId)
Faça com que seu canal padrão apareça antes que o app seja aberto. Para que isso aconteça, adicione um
BroadcastReceiverque detecte a açãoandroid.media.tv.action.INITIALIZE_PROGRAMS, que a tela inicial envia após a instalação do app:<receiver android:name=".RunOnInstallReceiver" android:exported="true"> <intent-filter> <action android:name="android.media.tv.action.INITIALIZE_PROGRAMS" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </receiver>Ao fazer o sideload do app durante o desenvolvimento, é possível testar essa etapa acionando a intent pelo adb, em que your.package.name/.YourReceiverName é o
BroadcastReceiverdo app:adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \ your.package.name/.YourReceiverNameEm casos raros, o app pode receber a transmissão ao mesmo tempo em que o usuário o inicia. Verifique se o código não tenta adicionar o canal padrão mais de uma vez.
Como atualizar um canal
Atualizar canais é muito semelhante a criá-los.
Use outro Channel.Builder para definir os atributos que precisam ser mudados.
Use ContentResolver para atualizar o canal. Use o ID do canal que você
salvou quando o canal foi adicionado originalmente:
context.contentResolver.update( TvContractCompat.buildChannelUri(channelId), builder.build().toContentValues(), null, null )
Para atualizar o logotipo de um canal, use storeChannelLogo().
Como excluir um canal
context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)
Programas
Os programas são os cards de conteúdo individuais mostrados em um canal. É possível publicar programas nos canais personalizados do app e no canal Assistir em seguida, gerenciado pelo sistema.
Como adicionar programas a um canal do app
Crie um PreviewProgram.Builder e defina os atributos:
val builder = PreviewProgram.Builder() builder.setChannelId(channelId) .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP) .setTitle("Title") .setDescription("Program description") .setPosterArtUri(uri) .setIntentUri(uri) .setInternalProviderId(appProgramId)
Adicione mais atributos dependendo do tipo de programa. Para conferir os atributos disponíveis para cada tipo de programa, consulte as tabelas abaixo.
Insira o programa no provedor:
var programUri = context.contentResolver.insert( TvContractCompat.PreviewPrograms.CONTENT_URI, builder.build().toContentValues() )
Recupere o ID do programa para referência futura:
val programId = ContentUris.parseId(programUri)
Como adicionar programas ao canal "Assistir a seguir"
Para inserir programas no canal "Assistir a seguir", consulte Adicionar programas ao canal "Assistir a seguir".
Como atualizar um programa
Você pode mudar as informações de um programa. Por exemplo, talvez você queira atualizar o preço de aluguel de um filme ou uma barra de progresso que mostra quanto de um programa o usuário assistiu.
Use um PreviewProgram.Builder para definir os atributos que você precisa mudar e, em seguida,
chame getContentResolver().update para atualizar o programa. Especifique o ID do programa
que você salvou quando o programa foi adicionado originalmente:
context.contentResolver.update( TvContractCompat.buildPreviewProgramUri(programId), builder.build().toContentValues(), null, null )
Como excluir um programa
context.contentResolver .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)
Como lidar com ações do usuário
Seu app pode ajudar os usuários a descobrir conteúdo fornecendo uma interface para exibir e adicionar canais. Seu app também precisa processar as interações com os canais depois que eles aparecem na tela inicial.
Como descobrir e adicionar canais
O app pode fornecer um elemento da interface que permite ao usuário selecionar e adicionar os canais dele (por exemplo, um botão que solicita a adição do canal).
Depois que o usuário solicitar um canal específico, execute este código para receber a permissão dele para adicioná-lo à interface da tela inicial:
val intent = Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE)
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId)
try {
activity.startActivityForResult(intent, 0)
} catch (e: ActivityNotFoundException) {
// handle error
}
O sistema exibe uma caixa de diálogo solicitando que o usuário aprove o canal. Processe o
resultado da solicitação no método onActivityResult da atividade
(Activity.RESULT_CANCELED ou Activity.RESULT_OK).
Eventos da tela inicial do Android TV
Quando o usuário interage com os programas e canais publicados pelo app, a tela inicial envia intents para o app:
- A tela inicial envia o
Uriarmazenado no atributo APP_LINK_INTENT_URI de um canal para o app quando o usuário seleciona o logotipo do canal. O app precisa apenas iniciar a interface principal ou uma visualização relacionada ao canal selecionado. - A tela inicial envia o
Uriarmazenado no atributo INTENT_URI de um programa para o app quando o usuário seleciona um programa. O app vai reproduzir o conteúdo selecionado. - O usuário pode indicar que não tem mais interesse em um programa e quer que ele seja removido da interface da tela inicial. O sistema remove o programa da interface e envia ao app proprietário uma intent (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED ou android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) com o ID do programa. O app precisa remover o programa do provedor e NÃO pode reinseri-lo.
Crie filtros de intent para todas as Uris que a tela inicial
envia para interações do usuário, por exemplo:
<receiver
android:name=".WatchNextProgramRemoved"
android:enabled="true"
android:exported="true">
<intent-filter>
<action android:name="android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED" />
</intent-filter>
</receiver>
Outras considerações
- Muitos apps de TV exigem que os usuários façam login. Nesse caso, o
BroadcastReceiverque detectaandroid.media.tv.action.INITIALIZE_PROGRAMSprecisa sugerir conteúdo do canal para usuários não autenticados. Por exemplo, o app pode mostrar inicialmente o melhor conteúdo ou o conteúdo em alta no momento. Depois que o usuário faz login, ele pode mostrar conteúdo personalizado. Essa é uma ótima chance para os apps fazerem upsell para os usuários antes do login. - Quando o app não estiver em primeiro plano e você precisar atualizar um canal ou um
programa, use o
JobSchedulerpara programar o trabalho (consulteJobSchedulereJobService). - O sistema pode revogar as permissões do provedor do app se ele se comportar de maneira inadequada (por exemplo, enviar spam continuamente para o provedor com dados). Envolva o código que acessa o provedor com cláusulas try-catch para processar exceções de segurança.
- Antes de atualizar programas e canais, consulte o provedor para saber quais dados precisam ser atualizados e reconcilie os dados. Por exemplo, não é necessário atualizar um programa que o usuário quer remover da interface. Use um job em segundo plano que insira ou atualize seus dados no provedor depois de consultar os dados atuais e solicitar aprovação para seus canais. Você pode executar esse job quando o app for iniciado e sempre que ele precisar atualizar os dados.
context.contentResolver .query( TvContractCompat.buildChannelUri(channelId), null, null, null, null ).use({ cursor -> if (cursor != null && cursor.moveToNext()) { val channel = Channel.fromCursor(cursor) if (channel.isBrowsable()) { // update channel's programs. } } })
- Use URIs exclusivos para todas as imagens (logotipos, ícones, imagens de conteúdo). Use um Uri diferente ao atualizar uma imagem. Todas as imagens são armazenadas em cache. Se você não mudar o URI ao alterar a imagem, a imagem antiga vai continuar aparecendo.
- Lembre-se de que as cláusulas WHERE não são permitidas, e as chamadas para os provedores com cláusulas WHERE vão gerar uma exceção de segurança.
Atributos
Esta seção descreve os atributos do canal e do programa separadamente.
Atributos do canal
Você precisa especificar estes atributos para cada canal:
| Atributo | Observações |
|---|---|
| TYPE | defina como TYPE_PREVIEW. |
| DISPLAY_NAME | defina como o nome do canal. |
| APP_LINK_INTENT_URI | Quando o usuário seleciona o logotipo do canal, o sistema envia um intent para iniciar uma atividade que apresenta conteúdo relevante para o canal. Defina esse atributo como o URI usado no filtro de intent dessa atividade. |
Além disso, um canal também tem seis campos reservados para uso interno do app. Esses campos podem ser usados para armazenar chaves ou outros valores que podem ajudar o app a mapear o canal para a estrutura de dados interna:
- INTERNAL_PROVIDER_ID
- INTERNAL_PROVIDER_DATA
- INTERNAL_PROVIDER_FLAG1
- INTERNAL_PROVIDER_FLAG2
- INTERNAL_PROVIDER_FLAG3
- INTERNAL_PROVIDER_FLAG4
Atributos do programa
Veja as páginas individuais para os atributos de cada tipo de programa:
- Atributos do programa de vídeo
- Atributos do programa de áudio
- Atributos do programa de jogo
- Atributos do programa do "Assistir a seguir"
Exemplo de código
Para saber mais sobre como criar apps que interagem com a tela inicial e adicionar canais e programas à tela inicial do Android TV, consulte nosso codelab sobre a tela inicial.