La schermata Home di Android TV fornisce una UI che mostra i contenuti consigliati sotto forma di tabella di canali e programmi. Ogni riga rappresenta un canale. Un canale contiene schede per ogni programma disponibile su quel canale:
Questo documento mostra come aggiungere canali e programmi alla schermata Home, aggiornare i contenuti, gestire le azioni degli utenti e offrire la migliore esperienza possibile agli utenti. (Se vuoi approfondire l'API, prova il codelab della schermata Home e guarda la sessione di Android TV di I/O 2017).
La UI della schermata Home
Le app possono creare nuovi canali, aggiungere, rimuovere e aggiornare i programmi in un canale e controllare l'ordine dei programmi in un canale. Ad esempio, un'app può creare un canale chiamato "Novità" e mostrare schede per i programmi appena resi disponibili.
Le app non possono controllare l'ordine in cui i canali vengono visualizzati nella schermata Home. Quando l'app crea un nuovo canale, la schermata Home lo aggiunge in fondo all'elenco dei canali. L'utente può riordinare, nascondere e mostrare i canali.
Il canale Cosa guardare
Il canale Guarda i prossimi è la seconda riga visualizzata nella schermata Home, dopo la riga delle app. Il sistema crea e gestisce questo canale. La tua app può aggiungere programmi al canale Cosa guardare. Per saperne di più, consulta Aggiungi programmi al canale Cosa guardare.
Canali per app
I canali creati dalla tua app seguono tutti questo ciclo di vita:
- L'utente scopre un canale nella tua app e richiede di aggiungerlo alla schermata Home.
- L'app crea il canale e lo aggiunge a
TvProvider(a questo punto il canale non è visibile). - L'app chiede al sistema di visualizzare il canale.
- Il sistema chiede all'utente di approvare il nuovo canale.
- Il nuovo canale viene visualizzato nell'ultima riga della schermata Home.
Il canale predefinito
La tua app può offrire un numero qualsiasi di canali che l'utente può aggiungere alla schermata Home. In genere, l'utente deve selezionare e approvare ogni canale prima che venga visualizzato nella schermata Home. Ogni app ha la possibilità di creare un canale predefinito. Il canale predefinito è speciale perché viene visualizzato automaticamente nella schermata Home; l'utente non deve richiederlo esplicitamente.
Prerequisiti
La schermata Home di Android TV utilizza le API TvProvider di Android per gestire i canali e i programmi creati dalla tua app. Per accedere ai dati del provider, aggiungi
la seguente autorizzazione al manifest dell'app:
<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
La libreria di supporto TvProvider semplifica l'utilizzo del provider. Aggiungila alle dipendenze nel file build.gradle:
Alla moda
implementation 'androidx.tvprovider:tvprovider:1.0.0'
Kotlin
implementation("androidx.tvprovider:tvprovider:1.0.0")
Per utilizzare canali e programmi, assicurati di includere queste importazioni della libreria di supporto nel tuo programma:
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
Canali
Il primo canale creato dalla tua app diventa il canale predefinito. Il canale predefinito viene visualizzato automaticamente nella schermata Home. Tutti gli altri canali che crei devono essere selezionati e accettati dall'utente prima di poter essere visualizzati nella schermata Home.
Creazione di un canale
L'app deve chiedere al sistema di mostrare i canali appena aggiunti solo quando è in esecuzione in primo piano. In questo modo, l'app non visualizza una finestra di dialogo che richiede l'approvazione per l'aggiunta del canale mentre l'utente esegue un'altra app. Se provi ad aggiungere un canale mentre l'app è in esecuzione in background, il metodo onActivityResult() dell'attività restituisce il codice di stato RESULT_CANCELED.
Per creare un canale, segui questi passaggi:
Crea un generatore di canali e imposta i relativi attributi. Tieni presente che il tipo di canale deve essere
TYPE_PREVIEW. Aggiungi altri attributi in base alle tue esigenze.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)
Inserisci il canale nel provider:
var channelUri = context.contentResolver.insert( TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues() )
Devi salvare l'ID canale per aggiungere programmi al canale in un secondo momento. Estrai l'ID canale dall'URI restituito:
var channelId = ContentUris.parseId(channelUri)
Devi aggiungere un logo per il tuo canale. Utilizza
UrioBitmap. L'icona del logo deve essere di 80 x 80 dp e deve essere opaca. Viene visualizzato sotto una maschera circolare:
// Choose one or the other. storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL. storeChannelLogo(context, channelId, logo)
Crea il canale predefinito (facoltativo): quando la tua app crea il suo primo canale, puoi impostarlo come canale predefinito in modo che venga visualizzato immediatamente nella schermata Home senza alcuna azione da parte dell'utente. Gli altri canali che crei non sono visibili finché l'utente non li seleziona esplicitamente.
TvContractCompat.requestChannelBrowsable(context, channelId)
Fai in modo che il tuo canale predefinito venga visualizzato prima dell'apertura dell'app. Puoi ottenere questo comportamento aggiungendo un
BroadcastReceiverche ascolta l'azioneandroid.media.tv.action.INITIALIZE_PROGRAMS, che la schermata Home invia dopo l'installazione dell'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>Quando esegui il sideload dell'app durante lo sviluppo, puoi testare questo passaggio attivando l'intent tramite adb, dove your.package.name/.YourReceiverName è il
BroadcastReceiverdell'app:adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \ your.package.name/.YourReceiverNameIn rari casi, la tua app potrebbe ricevere la trasmissione nello stesso momento in cui l'utente la avvia. Assicurati che il tuo codice non tenti di aggiungere il canale predefinito più di una volta.
Aggiornamento di un canale
L'aggiornamento dei canali è molto simile alla loro creazione.
Utilizza un altro Channel.Builder per impostare gli attributi da modificare.
Utilizza ContentResolver per aggiornare il canale. Utilizza l'ID canale che hai salvato quando il canale è stato aggiunto originariamente:
context.contentResolver.update( TvContractCompat.buildChannelUri(channelId), builder.build().toContentValues(), null, null )
Per aggiornare il logo di un canale, utilizza storeChannelLogo().
Eliminazione di un canale
context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)
Programmi
I programmi sono le singole schede di contenuti visualizzate all'interno di un canale. Puoi pubblicare programmi sia sui canali personalizzati della tua app sia sul canale Cosa guardare gestito dal sistema.
Aggiunta di programmi a un canale dell'app
Crea un PreviewProgram.Builder e imposta i relativi attributi:
val builder = PreviewProgram.Builder() builder.setChannelId(channelId) .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP) .setTitle("Title") .setDescription("Program description") .setPosterArtUri(uri) .setIntentUri(uri) .setInternalProviderId(appProgramId)
Aggiungi altri attributi a seconda del tipo di programma. Per visualizzare gli attributi disponibili per ogni tipo di programma, consulta le tabelle di seguito.
Inserisci il programma nel provider:
var programUri = context.contentResolver.insert( TvContractCompat.PreviewPrograms.CONTENT_URI, builder.build().toContentValues() )
Recupera l'ID programma per riferimento futuro:
val programId = ContentUris.parseId(programUri)
Aggiunta di programmi al canale Cosa guardare
Per inserire programmi nel canale Cosa guardare, consulta Aggiungi programmi al canale Cosa guardare.
Aggiornamento di un programma
Puoi modificare le informazioni di un programma. Ad esempio, potresti voler aggiornare il prezzo di noleggio di un film o aggiornare una barra di avanzamento che mostra la parte di un programma che l'utente ha guardato.
Utilizza un PreviewProgram.Builder per impostare gli attributi che devi modificare, quindi chiama getContentResolver().update per aggiornare il programma. Specifica l'ID programma che hai salvato quando il programma è stato aggiunto originariamente:
context.contentResolver.update( TvContractCompat.buildPreviewProgramUri(programId), builder.build().toContentValues(), null, null )
Eliminazione di un programma
context.contentResolver .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)
Gestione delle azioni utente
La tua app può aiutare gli utenti a scoprire i contenuti fornendo una UI per visualizzare e aggiungere canali. L'app deve anche gestire le interazioni con i canali dopo che vengono visualizzati nella schermata Home.
Scoprire e aggiungere canali
La tua app può fornire un elemento UI che consente all'utente di selezionare e aggiungere i propri canali (ad esempio, un pulsante che chiede di aggiungere il canale).
Dopo che l'utente ha richiesto un canale specifico, esegui questo codice per ottenere l'autorizzazione dell'utente ad aggiungerlo alla UI della schermata Home:
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
}
Il sistema visualizza una finestra di dialogo che chiede all'utente di approvare il canale. Gestisci il risultato della richiesta nel metodo onActivityResult della tua attività (Activity.RESULT_CANCELED o Activity.RESULT_OK).
Eventi della schermata Home di Android TV
Quando l'utente interagisce con i programmi e i canali pubblicati dall'app, la schermata Home invia intent all'app:
- La schermata Home invia all'app l'URI
Urimemorizzato nell'attributo APP_LINK_INTENT_URI di un canale quando l'utente seleziona il logo del canale. L'app deve solo avviare la sua UI principale o una visualizzazione correlata al canale selezionato. - La schermata Home invia all'app l'
Urimemorizzato nell'attributo INTENT_URI di un programma quando l'utente seleziona un programma. L'app dovrebbe riprodurre i contenuti selezionati. - L'utente può indicare che non è più interessato a un programma e vuole che venga rimosso dalla UI della schermata Home. Il sistema rimuove il programma dalla UI e invia all'app proprietaria del programma un intent (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED o android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) con l'ID del programma. L'app deve rimuovere il programma dal provider e NON deve reinserirlo.
Assicurati di creare filtri per intent per tutti i Uris che la schermata Home invia per le interazioni utente, ad esempio:
<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>
Considerazioni aggiuntive
- Molte app TV richiedono l'accesso degli utenti. In questo caso,
BroadcastReceiverche ascoltaandroid.media.tv.action.INITIALIZE_PROGRAMSdovrebbe suggerire i contenuti del canale per gli utenti non autenticati. Ad esempio, l'app può mostrare inizialmente i contenuti migliori o quelli attualmente più popolari. Dopo l'accesso dell'utente, può mostrare contenuti personalizzati. Questa è un'ottima opportunità per le app di fare up-selling agli utenti prima che accedano. - Quando la tua app non è in primo piano e devi aggiornare un canale o un programma, utilizza
JobSchedulerper pianificare il lavoro (consultaJobSchedulereJobService). - Il sistema può revocare le autorizzazioni del provider della tua app se quest'ultima non si comporta correttamente (ad esempio, se invia continuamente spam al provider con dati). Assicurati di racchiudere il codice che accede al provider con clausole try-catch per gestire le eccezioni di sicurezza.
- Prima di aggiornare programmi e canali, chiedi al provider i dati che devi aggiornare e riconcilia i dati. Ad esempio, non è necessario aggiornare un programma che l'utente vuole rimuovere dalla UI. Utilizza un job in background che inserisca o aggiorni i dati nel provider dopo aver eseguito una query sui dati esistenti e aver richiesto l'approvazione per i tuoi canali. Puoi eseguire questo job all'avvio dell'app e ogni volta che l'app deve aggiornare i suoi dati.
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. } } })
- Utilizza URI univoci per tutte le immagini (loghi, icone, immagini dei contenuti). Assicurati di utilizzare un URI diverso quando aggiorni un'immagine. Tutte le immagini vengono memorizzate nella cache. Se non modifichi l'URI quando cambi l'immagine, continuerà a essere visualizzata l'immagine precedente.
- Ricorda che le clausole WHERE non sono consentite e le chiamate ai provider con clausole WHERE genereranno un'eccezione di sicurezza.
Attributi
Questa sezione descrive separatamente gli attributi del canale e del programma.
Attributi del canale
Devi specificare questi attributi per ogni canale:
| Attributo | Note |
|---|---|
| TIPO | impostato su TYPE_PREVIEW. |
| DISPLAY_NAME | impostato sul nome del canale. |
| APP_LINK_INTENT_URI | Quando l'utente seleziona il logo del canale, il sistema invia un intent per avviare un'attività che presenta contenuti pertinenti al canale. Imposta questo attributo sull'URI utilizzato nel filtro per intent per l'attività. |
Inoltre, un canale ha anche sei campi riservati per l'utilizzo interno dell'app. Questi campi possono essere utilizzati per archiviare chiavi o altri valori che possono aiutare l'app a mappare il canale alla sua struttura di dati interna:
- INTERNAL_PROVIDER_ID
- INTERNAL_PROVIDER_DATA
- INTERNAL_PROVIDER_FLAG1
- INTERNAL_PROVIDER_FLAG2
- INTERNAL_PROVIDER_FLAG3
- INTERNAL_PROVIDER_FLAG4
Attributi del programma
Consulta le singole pagine degli attributi per ogni tipo di programma:
- Attributi del programma video
- Attributi del programma audio
- Attributi del programma di giochi
- Attributi del programma Guarda successivo
Codice di esempio
Per scoprire di più sulla creazione di app che interagiscono con la schermata Home e sull'aggiunta di canali e programmi alla schermata Home di Android TV, consulta il nostro codelab sulla schermata Home.