Chaînes sur l'écran d'accueil

L'écran d'accueil d'Android TV fournit une interface utilisateur qui affiche les contenus recommandés sous la forme d'un tableau de chaînes et de programmes. Chaque ligne correspond à une chaîne. Une chaîne contient des fiches pour chaque programme disponible sur cette chaîne :

Écran d'accueil d'Android TV
Écran d'accueil d'Android TV

Ce document explique comment ajouter des chaînes et des programmes à l'écran d'accueil, mettre à jour le contenu, gérer les actions des utilisateurs et leur offrir la meilleure expérience possible. (Si vous souhaitez en savoir plus sur l'API, essayez l'atelier de programmation sur l'écran d'accueil et regardez la session Android TV de l'I/O 2017.)

UI de l'écran d'accueil

Les applications peuvent créer des chaînes, ajouter, supprimer et mettre à jour les programmes d'une chaîne, et contrôler l'ordre des programmes d'une chaîne. Par exemple, une application peut créer une chaîne intitulée "Nouveautés" et afficher des fiches pour les programmes récemment disponibles.

Les applications ne peuvent pas contrôler l'ordre d'affichage des chaînes sur l'écran d'accueil. Lorsque votre application crée une chaîne, l'écran d'accueil l'ajoute au bas de la liste des chaînes. L'utilisateur peut réorganiser, masquer et afficher les chaînes.

La chaîne "À regarder ensuite"

La chaîne « À regarder ensuite » est la deuxième ligne qui s'affiche sur l'écran d'accueil, après la ligne des applications. Le système crée et gère cette chaîne. Votre application peut ajouter des programmes à la chaîne "À regarder ensuite". Pour en savoir plus, consultez Ajouter des programmes à la chaîne "À regarder ensuite".

Canaux d'application

Les canaux créés par votre application suivent tous ce cycle de vie :

  1. L'utilisateur découvre une chaîne dans votre application et demande à l'ajouter à l'écran d'accueil.
  2. L'application crée la chaîne et l'ajoute à TvProvider (à ce stade, la chaîne n'est pas visible).
  3. L'application demande au système d'afficher la chaîne.
  4. Le système demande à l'utilisateur d'approuver le nouveau canal.
  5. La nouvelle chaîne apparaît sur la dernière ligne de l'écran d'accueil.

La chaîne par défaut

Votre application peut proposer un nombre illimité de chaînes que l'utilisateur peut ajouter à l'écran d'accueil. L'utilisateur doit généralement sélectionner et approuver chaque chaîne avant qu'elle n'apparaisse sur l'écran d'accueil. Chaque application peut créer un canal par défaut. Le canal par défaut est spécial, car il apparaît automatiquement sur l'écran d'accueil. L'utilisateur n'a pas besoin de le demander explicitement.

Prérequis

L'écran d'accueil d'Android TV utilise les API TvProvider d'Android pour gérer les chaînes et les programmes créés par votre application. Pour accéder aux données du fournisseur, ajoutez l'autorisation suivante au fichier manifeste de votre application :

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

La bibliothèque d'assistance TvProvider facilite l'utilisation du fournisseur. Ajoutez-la aux dépendances de votre fichier build.gradle :

Groovy

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

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

Pour utiliser des chaînes et des programmes, veillez à inclure ces importations de bibliothèques d'assistance dans votre programme :

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

Chaînes

Le premier canal créé par votre application devient son canal par défaut. La chaîne par défaut s'affiche automatiquement sur l'écran d'accueil. Toutes les autres chaînes que vous créez doivent être sélectionnées et acceptées par l'utilisateur avant de pouvoir apparaître sur l'écran d'accueil.

Créer une chaîne

Votre application ne doit demander au système d'afficher les nouvelles chaînes que lorsqu'elle s'exécute au premier plan. Cela empêche votre application d'afficher une boîte de dialogue demandant l'autorisation d'ajouter votre chaîne pendant que l'utilisateur exécute une autre application. Si vous essayez d'ajouter une chaîne pendant l'exécution en arrière-plan, la méthode onActivityResult() de l'activité renvoie le code d'état RESULT_CANCELED.

Pour créer un canal, procédez comme suit :

  1. Créez un compilateur de canaux et définissez ses attributs. Notez que le type de canal doit être TYPE_PREVIEW. Ajoutez d'autres attributs si nécessaire.

    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)

  2. Insérez le canal dans le fournisseur :

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

  3. Vous devez enregistrer l'ID de la chaîne pour pouvoir y ajouter des programmes ultérieurement. Extrayez l'ID de la chaîne de l'URI renvoyé :

    var channelId = ContentUris.parseId(channelUri)

  4. Vous devez ajouter un logo pour votre chaîne. Utilisez un Uri ou un Bitmap. L'icône du logo doit mesurer 80 dp x 80 dp et être opaque. Il s'affiche sous un masque circulaire :

    Masque de l'icône de l'écran d'accueil de la TV

    // Choose one or the other.
    storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL.
    storeChannelLogo(context, channelId, logo)

  5. Créer la chaîne par défaut (facultatif) : lorsque votre application crée sa première chaîne, vous pouvez en faire la chaîne par défaut afin qu'elle apparaisse immédiatement sur l'écran d'accueil sans aucune action de l'utilisateur. Les autres canaux que vous créez ne sont pas visibles tant que l'utilisateur ne les sélectionne pas explicitement.

    TvContractCompat.requestChannelBrowsable(context, channelId)

  6. Faites en sorte que votre chaîne par défaut s'affiche avant l'ouverture de votre application. Pour ce faire, ajoutez un BroadcastReceiver qui écoute l'action android.media.tv.action.INITIALIZE_PROGRAMS, que l'écran d'accueil envoie une fois l'application installée :

    <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>
    

    Lorsque vous téléchargez indépendamment votre application pendant le développement, vous pouvez tester cette étape en déclenchant l'intent via adb, où your.package.name/.YourReceiverName est le BroadcastReceiver de votre application :

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

    Dans de rares cas, votre application peut recevoir la diffusion en même temps que l'utilisateur la démarre. Assurez-vous que votre code n'essaie pas d'ajouter la chaîne par défaut plusieurs fois.

Mettre à jour un canal

La mise à jour des canaux est très similaire à leur création.

Utilisez un autre Channel.Builder pour définir les attributs à modifier.

Utilisez ContentResolver pour mettre à jour le canal. Utilisez l'ID de la chaîne que vous avez enregistré lors de l'ajout initial de la chaîne :

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

Pour mettre à jour le logo d'un canal, utilisez storeChannelLogo().

Supprimer un canal

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

Programmes

Les programmes sont les fiches de contenu individuelles affichées dans une chaîne. Vous pouvez publier des programmes à la fois sur les canaux personnalisés de votre application et sur le canal "À regarder ensuite" géré par le système.

Ajouter des programmes à une chaîne d'application

Créez un PreviewProgram.Builder et définissez ses attributs :

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

Ajoutez d'autres attributs en fonction du type de programme. (Pour connaître les attributs disponibles pour chaque type de programme, consultez les tableaux ci-dessous.)

Insérez le programme dans le fournisseur :

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

Récupérez l'ID du programme pour pouvoir vous y référer ultérieurement :

val programId = ContentUris.parseId(programUri)

Ajouter des programmes à la chaîne "À regarder ensuite"

Pour insérer des programmes dans la chaîne "À regarder ensuite", consultez Ajouter des programmes à la chaîne "À regarder ensuite".

Mettre à jour un programme

Vous pouvez modifier les informations d'un programme. Par exemple, vous pouvez mettre à jour le prix de location d'un film ou mettre à jour une barre de progression indiquant la durée d'un programme que l'utilisateur a regardé.

Utilisez un PreviewProgram.Builder pour définir les attributs que vous devez modifier, puis appelez getContentResolver().update pour mettre à jour le programme. Spécifiez l'ID du programme que vous avez enregistré lors de l'ajout initial du programme :

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

Supprimer un programme

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

Gérer les actions des utilisateurs

Votre application peut aider les utilisateurs à découvrir du contenu en fournissant une UI pour afficher et ajouter des chaînes. Votre application doit également gérer les interactions avec vos chaînes une fois qu'elles apparaissent sur l'écran d'accueil.

Découvrir et ajouter des canaux

Votre application peut fournir un élément d'interface utilisateur permettant à l'utilisateur de sélectionner et d'ajouter ses chaînes (par exemple, un bouton qui demande d'ajouter la chaîne).

Une fois que l'utilisateur a demandé une chaîne spécifique, exécutez ce code pour obtenir l'autorisation de l'ajouter à l'interface utilisateur de l'écran d'accueil :

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
}

Le système affiche une boîte de dialogue demandant à l'utilisateur d'approuver le canal. Gérez le résultat de la requête dans la méthode onActivityResult de votre activité (Activity.RESULT_CANCELED ou Activity.RESULT_OK).

Événements de l'écran d'accueil d'Android TV

Lorsque l'utilisateur interagit avec les programmes et les chaînes publiés par l'application, l'écran d'accueil envoie des intents à l'application :

  • L'écran d'accueil envoie l'Uri stocké dans l'attribut APP_LINK_INTENT_URI d'une chaîne à l'application lorsque l'utilisateur sélectionne le logo de la chaîne. L'application doit simplement lancer son UI principale ou une vue liée à la chaîne sélectionnée.
  • L'écran d'accueil envoie l'Uri stocké dans l'attribut INTENT_URI d'un programme à l'application lorsque l'utilisateur sélectionne un programme. L'application doit lire le contenu sélectionné.
  • L'utilisateur peut indiquer qu'un programme ne l'intéresse plus et qu'il souhaite le supprimer de l'interface utilisateur de l'écran d'accueil. Le système supprime le programme de l'interface utilisateur et envoie à l'application propriétaire du programme un intent (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED ou android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) avec l'ID du programme. L'application doit supprimer le programme du fournisseur et ne doit PAS le réinsérer.

Veillez à créer des filtres d'intent pour tous les Uris que l'écran d'accueil envoie pour les interactions utilisateur, par exemple :

<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>

Informations complémentaires

  • De nombreuses applications TV exigent que les utilisateurs se connectent. Dans ce cas, le BroadcastReceiver qui écoute android.media.tv.action.INITIALIZE_PROGRAMS doit suggérer du contenu de chaîne pour les utilisateurs non authentifiés. Par exemple, votre application peut initialement afficher le meilleur contenu ou le contenu actuellement populaire. Une fois l'utilisateur connecté, il peut afficher du contenu personnalisé. C'est une excellente occasion pour les applications de vendre la gamme supérieure aux utilisateurs avant qu'ils ne se connectent.
  • Lorsque votre application n'est pas au premier plan et que vous devez mettre à jour une chaîne ou un programme, utilisez JobScheduler pour planifier le travail (voir JobScheduler et JobService).
  • Le système peut révoquer les autorisations du fournisseur de votre application si celle-ci ne se comporte pas correctement (par exemple, si elle envoie continuellement des données au fournisseur). Veillez à encapsuler le code qui accède au fournisseur avec des clauses try-catch pour gérer les exceptions de sécurité.
  • Avant de mettre à jour les programmes et les chaînes, interrogez le fournisseur pour obtenir les données que vous devez mettre à jour et rapprocher. Par exemple, il n'est pas nécessaire de mettre à jour un programme que l'utilisateur souhaite supprimer de l'interface utilisateur. Utilisez un job en arrière-plan qui insère ou met à jour vos données dans le fournisseur après avoir interrogé les données existantes, puis demandez l'approbation de vos chaînes. Vous pouvez exécuter ce job au démarrage de l'application et chaque fois que l'application doit mettre à jour ses données.

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.
            }
        }
    })

  • Utilisez des URI uniques pour toutes les images (logos, icônes, images de contenu). Veillez à utiliser un URI différent lorsque vous mettez à jour une image. Toutes les images sont mises en cache. Si vous ne modifiez pas l'URI lorsque vous changez l'image, l'ancienne image continuera de s'afficher.
  • N'oubliez pas que les clauses WHERE ne sont pas autorisées et que les appels aux fournisseurs avec des clauses WHERE génèrent une exception de sécurité.

Attributs

Cette section décrit séparément les attributs de chaîne et de programme.

Attributs de canal

Vous devez spécifier ces attributs pour chaque canal :

Attribut Remarques
TYPE définie sur TYPE_PREVIEW.
DISPLAY_NAME définie sur le nom du canal.
APP_LINK_INTENT_URI Lorsque l'utilisateur sélectionne le logo de la chaîne, le système envoie un intent pour lancer une activité qui présente du contenu pertinent pour la chaîne. Définissez cet attribut sur l'URI utilisé dans le filtre d'intent pour cette activité.

De plus, un canal comporte six champs réservés à l'utilisation interne de l'application. Ces champs peuvent être utilisés pour stocker des clés ou d'autres valeurs qui peuvent aider l'application à mapper la chaîne à sa structure de données interne :

  • INTERNAL_PROVIDER_ID
  • INTERNAL_PROVIDER_DATA
  • INTERNAL_PROVIDER_FLAG1
  • INTERNAL_PROVIDER_FLAG2
  • INTERNAL_PROVIDER_FLAG3
  • INTERNAL_PROVIDER_FLAG4

Attributs du programme

Consultez les pages individuelles des attributs pour chaque type de programme :

Exemple de code

Pour en savoir plus sur la création d'applications qui interagissent avec l'écran d'accueil et sur l'ajout de chaînes et de programmes à l'écran d'accueil d'Android TV, consultez notre atelier de programmation sur l'écran d'accueil.