Canali nella schermata Home

La schermata Home di Android TV, o semplicemente la schermata Home, fornisce un'interfaccia utente che mostra i contenuti consigliati sotto forma di tabella di canali e programmi. Ogni riga rappresenta un canale. Un canale contiene le schede per ogni programma disponibile su quel canale:

Questo documento illustra 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 sulla schermata Home e guarda la sessione di I/O su Android TV.

Nota: i canali per i consigli sono disponibili solo in Android 8.0 (livello API 26) e versioni successive. Devi utilizzarle per fornire consigli per le app eseguite in Android 8.0 (livello API 26) e versioni successive. A fornisce consigli per app eseguite su versioni precedenti di Android, la tua app deve utilizzare riga dei suggerimenti .

L'interfaccia utente della schermata Home

Le app possono creare nuovi canali, aggiungere, rimuovere e aggiornare i programmi di un canale, nonché controllare l'ordine dei programmi in un canale. Ad esempio, un'app può creare un canale chiamato "Novità". e mostrare le schede dei nuovi programmi disponibili.

Le app non possono controllare l'ordine di visualizzazione dei canali nella schermata Home. Quando l'app crea un nuovo canale, nella 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 Cosa guardare è la seconda riga visualizzata nella schermata Home, dopo nella riga delle app. Il sistema crea e gestisce questo canale. La tua app può aggiungere programmi sul canale Cosa guardare. Per ulteriori informazioni, vedi Aggiungere programmi a il canale Cosa guardare.

Nota: sulla schermata Home, il canale Cosa guardare ha l'etichetta Prossimi contenuti.

Canali dell'app

I canali creati dalla tua app seguono tutti questo ciclo di vita:

1. L'utente scopre un canale nella tua app e chiede di aggiungerlo alla schermata Home.
2. L'app crea il canale e lo aggiunge a TvProvider (a questo punto il canale non è visibile).
3. L'app chiede al sistema di visualizzare il canale.
4. Il sistema chiede all'utente di approvare il nuovo canale.
5. Il nuovo canale viene visualizzato nell'ultima riga della schermata Home.

Il canale predefinito

L'app può offrire all'utente un numero qualsiasi di canali da aggiungere alla schermata Home. Di solito l'utente deve selezionare e approvare ciascun canale prima che appaia 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 richiederla 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 fornitore, aggiungi la seguente autorizzazione al file manifest dell'app:

<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

Nota :l'autorizzazione READ_EPG_DATA è stata ritirata in Android M (API 23) ed è non serve più.

La libreria di assistenza TvProvider semplifica l'utilizzo del fornitore. Aggiungilo alle dipendenze nel tuo file build.gradle:

Alla moda

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

implementation("androidx.tvprovider:tvprovider:1.0.0")

Per lavorare con canali e programmi, assicurati di includere nel tuo programma le seguenti importazioni della raccolta di supporto:

Kotlin

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

Java

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 suo 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 dovrebbe chiedere al sistema di mostrare i canali appena aggiunti solo quando è in esecuzione in primo piano. In questo modo, l'app non mostrerà una finestra di dialogo che richiede l'approvazione per aggiungere il canale mentre l'utente esegue un'altra app. Se provi ad aggiungere un canale mentre esegui l'esecuzione in background, il metodo onActivityResult() dell'attività restituisce il codice di stato RESULT_CANCELED.

Per creare un canale:

1. Creare uno strumento per la creazione di canali e impostarne gli attributi. Tieni presente che il tipo di canale deve essere TYPE_PREVIEW. Aggiungi altro attributes come obbligatorio.

   Kotlin

   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)
   

   Java

   Channel.Builder builder = new Channel.Builder();
   // Every channel you create must have the type TYPE_PREVIEW
   builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
           .setDisplayName("Channel Name")
           .setAppLinkIntentUri(uri);
   

2. Inserisci il canale nel provider:

   Kotlin

   var channelUri = context.contentResolver.insert(
           TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues())
   

   Java

   Uri channelUri = context.getContentResolver().insert(
           TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues());
   

3. Devi salvare l'ID canale per poter aggiungere programmi al canale in un secondo momento. Estrai l'ID canale dall'URI restituito:

   Kotlin

   var channelId = ContentUris.parseId(channelUri)
   

   Java

   long channelId = ContentUris.parseId(channelUri);
   

4. Devi aggiungere un logo per il tuo canale. Usa un Uri o Bitmap. Il logo deve essere di 80 dp x 80 dp e deve essere opaca. Viene visualizzato sotto un maschera circolare:

   

   Kotlin

   // Choose one or the other
   storeChannelLogo(context: Context, channelId: Long, logoUri: Uri) // also works if logoUri is a URL
   storeChannelLogo(context: Context, channelId: Long, logo: Bitmap)
   

   Java

   // Choose one or the other
   storeChannelLogo(Context context, long channelId, Uri logoUri); // also works if logoUri is a URL
   storeChannelLogo(Context context, long channelId, Bitmap logo);
   

5. (Facoltativo) Crea il canale predefinito: quando la tua app crea la prima puoi renderlo il canale predefinito in modo che sia visibile nella home page immediatamente senza alcuna azione dell'utente. Eventuali altri canali che crei non sono visibili finché l'utente non è esplicitamente li seleziona.

   Kotlin

   TvContractCompat.requestChannelBrowsable(context, channelId)
   

   Java

   TvContractCompat.requestChannelBrowsable(context, channelId);
   

6. Fai in modo che il tuo canale predefinito venga visualizzato prima dell'apertura dell'app. Puoi Per fare in modo che questo comportamento si verifichi, aggiungi un elemento BroadcastReceiver che ascolti l'evento android.media.tv.action.INITIALIZE_PROGRAMS, ovvero 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 della tua app durante lo sviluppo, puoi testare questo passaggio che attivano l'intenzione tramite ADB, dove your.package.name/.YourReceiverName è la filosofia della tua app BroadcastReceiver:

   adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \
       your.package.name/.YourReceiverName
   

   In rari casi, la tua app potrebbe ricevere la trasmissione nello stesso momento in cui l'utente avvia l'app. 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.

Usa un altro Channel.Builder per impostare gli attributi da modificare.

Usa l'ContentResolver per aggiornare il canale. Utilizza l'ID canale che hai salvato al momento dell'aggiunta del canale:

Kotlin

context.contentResolver.update(
        TvContractCompat.buildChannelUri(channelId),
        builder.build().toContentValues(),
        null,
        null
)

Java

context.getContentResolver().update(TvContractCompat.buildChannelUri(channelId),
    builder.build().toContentValues(), null, null);

Per aggiornare il logo di un canale, utilizza storeChannelLogo().

Eliminare un canale

Kotlin

context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)

Java

context.getContentResolver().delete(TvContractCompat.buildChannelUri(channelId), null, null);

Nota: non devi mai eliminare il canale predefinito. In questo caso, l'utente dovrà selezionarlo di nuovo e chiedi di aggiungerlo alla schermata Home. Non può riapparire automaticamente. Una volta aggiunto di nuovo, verrà visualizzato nella parte inferiore della schermata Home, proprio come qualsiasi altro canale appena aggiunto.

Programmi

Aggiunta di programmi a un canale dell'app

Crea un PreviewProgram.Builder e impostane gli attributi:

Kotlin

val builder = PreviewProgram.Builder()
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId)

Java

PreviewProgram.Builder builder = new PreviewProgram.Builder();
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId);

Aggiungi altri attributi in base al tipo di programma. (per vedere gli attributi disponibili per ogni tipo di programma, consulta le tabelle riportate di seguito.

Inserisci il programma nel provider:

Kotlin

var programUri = context.contentResolver.insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
        builder.build().toContentValues())

Java

Uri programUri = context.getContentResolver().insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
      builder.build().toContentValues());

Recupera l'ID programma per riferimento futuro:

Kotlin

val programId = ContentUris.parseId(programUri)

Java

long programId = ContentUris.parseId(programUri);

Aggiunta di programmi al canale Cosa guardare

Per inserire programmi nel canale Cosa guardare, consulta l'articolo Aggiungere programmi alla sezione Cosa guardare. Canale successivo.

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 durata della visione di un programma da parte dell'utente.

Usa un PreviewProgram.Builder per impostare gli attributi da modificare, quindi chiama getContentResolver().update per aggiornare il programma. Specifica l'ID del programma che hai salvato quando il programma è stato originariamente aggiunto:

Kotlin

context.contentResolver.update(
        TvContractCompat.buildPreviewProgramUri(programId),
                builder.build().toContentValues(), null, null
)

Java

context.getContentResolver().update(TvContractCompat.buildPreviewProgramUri(programId),
    builder.build().toContentValues(), null, null);

Eliminazione di un programma

Kotlin

context.contentResolver
        .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)

Java

context.getContentResolver().delete(TvContractCompat.buildPreviewProgramUri(programId), null, null);

Gestione delle azioni degli utenti

La tua app può aiutare gli utenti a scoprire contenuti fornendo una UI per visualizzare e aggiungere canali. L'app dovrebbe anche gestire le interazioni con i tuoi canali dopo che sono state visualizzate nella schermata Home.

Individuazione e aggiunta di 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 ad aggiungerlo all'interfaccia utente della schermata Home:

Kotlin

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
}

Java

Intent intent = new Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE);
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId);
try {
   activity.startActivityForResult(intent, 0);
} catch (ActivityNotFoundException e) {
  // handle error
}

Il sistema visualizza una finestra di dialogo in cui all'utente viene chiesto di approvare il canale. Gestisci il risultato della richiesta nel metodo onActivityResult della tua attività (Activity.RESULT_CANCELED o Activity.RESULT_OK).

Eventi nella schermata Home di Android TV

Quando l'utente interagisce con i programmi/canali pubblicati dall'app, la schermata Home invia intent all'app:

• La schermata Home invia all'app il valore Uri memorizzato nell'attributo APP_LINK_INTENT_URI di un canale quando l'utente seleziona il logo del canale. L'app deve semplicemente avviare la sua UI principale o una visualizzazione correlata al canale selezionato.
• La schermata Home invia all'app il valore Uri memorizzato nell'attributo INTENT_URI di un programma quando l'utente seleziona un programma. L'app dovrebbe riprodurre i contenuti selezionati.
• L'utente può indicare di non essere più interessato a un programma e vuole che venga rimosso dall'interfaccia utente della schermata Home. Il sistema rimuove il programma dall'interfaccia utente e invia un intent (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED o android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) all'app proprietaria. L'app dovrebbe rimuovere il programma dal fornitore e NON deve reinserirlo.

Assicurati di creare filtri per intent per tutti i Uris che la schermata Home invia per le interazioni degli utenti. 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>

Best practice

• Molte app TV richiedono l'accesso degli utenti. In questo caso, BroadcastReceiver che ascolta android.media.tv.action.INITIALIZE_PROGRAMS dovrebbe suggerire i contenuti del canale per gli utenti non autenticati.Ad esempio, inizialmente la tua app può mostrare i contenuti migliori o quelli più popolari. Dopo che l'utente esegue l'accesso, possono mostrare contenuti personalizzati. È una grande opportunità per l'upsell presso le app utenti prima di effettuare l'accesso.
• Quando la tua app non è in primo piano e devi aggiornare un canale o un utilizza JobScheduler per programmare il lavoro (vedi: JobScheduler e JobService).
• Il sistema può revocare le autorizzazioni del provider dell'app se l'app non funziona (ad esempio: invio continuo di dati al provider). Assicurati di aggrega il codice che accede al provider con clausole trips-catch per gestire eccezioni di sicurezza.

• Prima di aggiornare programmi e canali, chiedi al fornitore i dati che aggiornare e riconciliare i dati. Ad esempio, non è necessario aggiornare un programma che l'utente vuole rimuovere dall'interfaccia utente. Utilizza un job in background che inserisce/aggiorna i dati nel provider dopo aver eseguito una query per l'attuale di contenuti e poi richiedere l'approvazione per i tuoi canali. Puoi eseguire questo job quando l'app si avvia e ogni volta che deve aggiornare i relativi dati.

  Kotlin

  context.contentResolver
    .query(
        TvContractCompat.buildChannelUri(channelId),
            null, null, null, null).use({
                cursor-> if (cursor != null and cursor.moveToNext()) {
                             val channel = Channel.fromCursor(cursor)
                             if (channel.isBrowsable()) {
                                 //update channel's programs
                             }
                         }
            })
  

  Java

  try (Cursor cursor = context.getContentResolver()
        .query(
            TvContractCompat.buildChannelUri(channelId),
            null,
            null,
            null,
            null)) {
                if (cursor != null && cursor.moveToNext()) {
                    Channel channel = Channel.fromCursor(cursor);
                    if (channel.isBrowsable()) {
                        //update channel's programs
                    }
                }
            }
  

• Utilizza URI univoci per tutte le immagini (loghi, icone, immagini di 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 quella precedente.

• Ricorda che le clausole WHERE non sono consentite e che le chiamate ai provider con clausole WHERE generano un'eccezione di sicurezza.

Attributi

In questa sezione vengono descritti gli attributi del canale e del programma separatamente.

Attributi del canale

Devi specificare questi attributi per ogni canale:

Attributo	Note
MACCHINA	impostato su TYPE_PREVIEW.
NOME_DISPLAY	impostata sul nome del canale.
APP_LINK_INTENT_URI	Quando l'utente seleziona il logo del canale, il sistema invia l'intenzione di avviare un'attività che presenti 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 all'utilizzo interno delle app. Questi campi possono essere utilizzati per archiviare chiavi o altri valori che possono aiutare l'app a mappare il canale alla struttura dei dati interni:

• ID_PROVIDER_INTERNO
• DATI_PROVIDER_INTERNI
• INTERNAL_PROVIDER_FLAG1
• INTERNAL_PROVIDER_FLAG2
• INTERNAL_PROVIDER_FLAG3
• INTERNAL_PROVIDER_FLAG4

Attributi del programma

Consulta le singole pagine per gli attributi per ogni tipo di programma:

• Attributi dei programmi video
• Attributi del programma audio
• Attributi dei programmi di gioco
• Attributi del programma Cosa guardare

Codice di esempio

Per scoprire di più sulla creazione di app che interagiscono con la schermata Home e aggiungere canali e programmi alla schermata Home di Android TV, consulta il nostro codelab sulla schermata Home.