Premiers pas avec les applications TV

Les applications TV utilisent la même structure que les applications pour téléphones et tablettes. Cette similitude signifie que vous pouvez modifier vos applications existantes pour qu'elles s'exécutent également sur les téléviseurs ou en créer d'autres en fonction de ce que vous savez déjà sur la création d'applications pour Android.

Important:Votre application doit répondre à des exigences spécifiques pour être considérée comme une application Android TV sur Google Play. Pour en savoir plus, consultez les exigences indiquées dans Qualité des applications TV.

Ce guide explique comment préparer votre environnement de développement à la création d'applications TV et présente les modifications minimales requises pour permettre l'exécution d'une application sur des téléviseurs.

Pour en savoir plus sur la conception d'applications pour la télévision, consultez la section Conception pour la télévision. Consultez également les exemples d'applications dans le dépôt GitHub Android TV.

Déterminer les formats multimédias compatibles

Consultez la documentation suivante pour en savoir plus sur les codecs, les protocoles et les formats compatibles avec Android TV:

• Formats multimédias compatibles
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

Configurer un projet TV

Cette section explique comment configurer un projet TV, que ce soit pour modifier une application Android existante pour qu'elle s'exécute sur des téléviseurs ou pour créer une application TV. Si vous disposez déjà d'une application Android, ajouter la prise en charge Android TV vous permet de concevoir une interface utilisateur pour TV tout en réutilisant l'architecture de votre application existante.

Remarque:Nous vous recommandons de n'avoir qu'une seule application compatible avec les appareils mobiles et les téléviseurs. Si vous avez besoin d'applications distinctes pour les appareils mobiles et les téléviseurs, vous pouvez publier plusieurs applications sous la même fiche sur Google Play en utilisant plusieurs fichiers APK. Pour en savoir plus, consultez Prendre en charge plusieurs fichiers APK.

Déclarer une activité TV

Une application destinée à s'exécuter sur des téléviseurs doit déclarer une activité de lanceur d'applications pour ce téléviseur dans son fichier manifeste. Pour ce faire, il utilise un filtre d'intent CATEGORY_LEANBACK_LAUNCHER. Ce filtre identifie votre application comme étant activée pour les téléviseurs et permet à Google Play de l'identifier en tant qu'application TV. Lorsqu'un utilisateur sélectionne votre application sur l'écran d'accueil de son téléviseur, cet intent identifie l'activité à lancer.

L'extrait de code suivant montre comment inclure ce filtre d'intent dans votre fichier manifeste:

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

Dans cet exemple, la deuxième entrée du fichier manifeste d'activité indique qu'il s'agit de l'activité à lancer sur un téléviseur.

Attention:Si vous n'incluez pas le filtre d'intent CATEGORY_LEANBACK_LAUNCHER dans votre application, il n'est pas visible par les utilisateurs qui exécutent Google Play sur des téléviseurs. De plus, si votre application ne dispose pas de ce filtre lorsque vous utilisez les outils pour les développeurs pour la charger sur un téléviseur, elle n'apparaîtra pas dans l'interface utilisateur du téléviseur.

L'interface utilisateur de votre application TV, ou la partie TV de votre application existante, doit fournir une interface simple pour faciliter la navigation à l'aide d'une télécommande située à trois mètres de distance. Si vous modifiez une application existante pour une utilisation sur un téléviseur, n'utilisez pas la même mise en page des activités pour les téléviseurs que pour les téléphones et les tablettes. Pour obtenir des directives sur la conception d'une application pour la télévision, consultez Concevoir une application pour la télévision. Pour en savoir plus sur la configuration minimale requise pour l'implémentation des mises en page d'interface sur TV, consultez Créer des mises en page TV.

Déclarer la compatibilité des téléviseurs

Déclarez que votre application est conçue pour Android TV en déclarant la fonctionnalité android.software.leanback.

Si votre application s'exécute à la fois sur mobile et sur téléviseur, définissez la valeur de l'attribut required sur false. Si vous définissez la valeur de l'attribut required sur true, Google Play ne proposera votre application que sur l'OS Android TV.

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

Déclarer l'écran tactile non requis

Les applications destinées à être exécutées sur des téléviseurs ne dépendent pas d'un écran tactile. Pour clarifier cela, le fichier manifeste de votre appli TV doit déclarer que la fonctionnalité android.hardware.touchscreen n'est pas requise. Ce paramètre détermine que votre appli fonctionne sur un téléviseur. Il est obligatoire pour qu'elle soit considérée comme une appli TV dans Google Play. L'exemple de code suivant montre comment inclure cette déclaration de fichier manifeste:

<manifest>
    <uses-feature android:name="android.hardware.touchscreen"
              android:required="false" />
    ...
</manifest>

Attention:Dans le fichier manifeste de votre application, vous devez déclarer qu'un écran tactile n'est pas requis, comme indiqué dans cet exemple de code. Sinon, votre appli n'apparaîtra pas dans Google Play sur les téléviseurs.

Fournir une icône et une bannière sur l'écran d'accueil

Les applications Android TV doivent fournir à la fois une icône sur l'écran d'accueil et une image de bannière pour chaque localisation. Selon l'appareil Android TV, l'icône ou la bannière est utilisée comme point de lancement de l'application qui apparaît sur l'écran d'accueil dans les lignes des applications et des jeux.

Pour les ajouter à votre application, décrivez l'icône et la bannière dans le fichier manifeste comme suit:

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

Icône de l'écran d'accueil

Les applications Android TV, comme toutes les applications Android, doivent disposer d'une icône d'écran d'accueil. Pour connaître les bonnes pratiques à suivre pour concevoir un excellent point de lancement pour votre application et connaître les exigences détaillées concernant les éléments, consultez les consignes relatives aux icônes et aux bannières des applications Android TV.

Bannière sur l'écran d'accueil

Utilisez l'attribut android:banner avec la balise <application> afin de fournir une bannière par défaut pour toutes les activités de l'application, ou avec la balise <activity> afin de fournir une bannière pour une activité spécifique.

Pour la bannière, utilisez une ressource xhdpi d'une taille de 320 x 180 px. L'image doit inclure du texte. Si votre application est disponible dans plusieurs langues, vous devez fournir des versions distinctes de la bannière avec du texte pour chaque langue compatible.

Modifier la couleur du lanceur d'applications

Attention:Sur Android 12 ou version ultérieure, les animations d'écran de démarrage personnalisées créées à l'aide de l'API de plate-forme SplashScreen ne sont pas compatibles avec les applications Android TV.

Lorsqu'une appli TV est lancée, le système affiche une animation qui ressemble à un cercle plein et extensible. Pour personnaliser la couleur de cette animation, définissez l'attribut android:colorPrimary de votre application ou activité TV sur une couleur spécifique. Définissez également deux attributs de chevauchement de transition sur true, comme indiqué dans l'extrait suivant d'un fichier XML de ressources de thème:

<resources>
    <style ... >
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>

Pour en savoir plus sur l'utilisation des thèmes et des styles, consultez la section Styles et thèmes.

Créer une application pour l'OS Android TV

La plupart des bibliothèques AndroidX peuvent être utilisées avec Android TV. Utilisez des composants d'architecture tels que ViewModel pour gérer les données d'UI tenant compte du cycle de vie, et Room pour intégrer les bases de données SQLite locales comme vous le feriez pour un appareil mobile.

La plupart des bibliothèques AndroidX sont compatibles avec Android TV. Les applications TV peuvent utiliser les mêmes composants d'architecture que les applications mobiles. Vous pouvez même partager des composants entre différents facteurs de forme. Il vous suffit donc de spécialiser la logique de présentation de votre application TV.

Compose pour la télévision

Utilisez Jetpack Compose pour créer l'UI de votre OS TV. Compose est le modèle Android moderne de développement d'UI. En plus des bibliothèques Compose principales, les bibliothèques Compose pour la télévision fournissent des composants dédiés conçus spécialement pour le grand écran:

• androidx.tv.foundation
• androidx.tv.material

Découvrez comment créer une application TV à l'aide de Compose pour la télévision dans Utiliser Jetpack Compose sur Android TV.

Kit d'interface utilisateur Leanback (déconseillé)

Le kit d'UI Leanback a toujours fourni des API et des widgets d'interface utilisateur exclusivement pour les téléviseurs utilisant des vues et des fragments Android:

• androidx.leanback.app
• androidx.leanback.database
• androidx.leanback.graphics
• androidx.leanback.media
• androidx.leanback.preference
• androidx.leanback.system
• androidx.leanback.widget
• androidx.leanback.widget.picker

Découvrez comment créer une application TV à l'aide du kit d'interface utilisateur Leanback dans Utiliser le kit d'interface utilisateur Leanback.

Exécuter des applications TV

L'exécution de votre application est une partie importante du processus de développement. Vous pouvez exécuter votre application sur des téléviseurs configurés pour prendre en charge le débogage USB ou utiliser des appareils de télévision virtuelle.

Exécuter l'application sur un appareil physique

Configurez votre téléviseur comme suit:

1. Utilisez un câble USB pour connecter votre téléviseur à votre ordinateur de développement. Si nécessaire, consultez la documentation fournie par le fabricant de votre appareil.
2. Sur votre téléviseur, accédez à Paramètres.
3. Sur la ligne Appareil, sélectionnez À propos.
4. Faites défiler la page jusqu'à Build (Compiler) et sélectionnez Build (Compiler) plusieurs fois jusqu'à ce que vous obteniez le message "You are now a developer!" (Vous êtes désormais un développeur).
5. Revenez aux Paramètres. Sur la ligne Préférences, sélectionnez Options pour les développeurs.
6. Sélectionnez Débogage > Débogage USB, puis Activé.
7. Revenez à l'écran d'accueil du téléviseur.

Pour tester votre application sur votre téléviseur:

1. Dans Android Studio, sélectionnez votre projet, puis cliquez sur Run (Exécuter) dans la barre d'outils.
2. Dans la fenêtre Select Deployment Target (Sélectionner une cible de déploiement), sélectionnez votre téléviseur, puis cliquez sur OK.

Exécuter l'application sur un appareil virtuel

AVD Manager du SDK Android fournit des définitions d'appareil qui vous permettent de créer des appareils de télévision virtuelle pour exécuter et tester vos applications.

Pour créer un appareil de télévision virtuelle:

1. Lancez AVD Manager. Pour en savoir plus, consultez la page Créer et gérer des appareils virtuels.
2. Dans la boîte de dialogue AVD Manager, cliquez sur l'onglet Device Definitions (Définitions d'appareils).
3. Sélectionnez l'une des définitions d'appareil Android TV, puis cliquez sur Créer un AVD.
4. Sélectionnez les options de l'émulateur, puis cliquez sur OK pour créer l'AVD.

   Remarque:Pour optimiser les performances de l'émulateur TV, utilisez l'émulateur x86 et activez l'option Use Host GPU (Utiliser le GPU de l'hôte). Utilisez également l'accélération d'appareil virtuel lorsqu'elle est disponible. Pour en savoir plus sur l'accélération matérielle de l'émulateur, consultez Configurer l'accélération matérielle pour Android Emulator.

Pour tester votre application sur l'appareil de télévision virtuelle:

1. Dans Android Studio, sélectionnez votre projet, puis cliquez sur Run (Exécuter) dans la barre d'outils.
2. Dans la fenêtre Select Deployment Target (Sélectionner une cible de déploiement), sélectionnez votre appareil de télévision virtuelle, puis cliquez sur OK.

Pour en savoir plus sur l'utilisation des émulateurs, consultez Exécuter des applications sur Android Emulator. Pour en savoir plus sur le déploiement d'applications à partir d'Android Studio sur des appareils virtuels, consultez Déboguer votre application.

Permettre à votre application TV de s'exécuter en tant qu'expérience instantanée

Les expériences instantanées permettent aux utilisateurs d'essayer facilement votre application TV et peuvent contribuer à augmenter l'adoption.

Pour configurer votre application TV afin qu'elle s'exécute en tant qu'application instantanée sur un appareil ou un émulateur Android TV, suivez d'abord les instructions pour créer un app bundle permettant une utilisation instantanée.

Ensuite, dans le intent-filter du MainActivity de votre application TV, assurez-vous que LAUNCHER et LEANBACK_LAUNCHER sont déclarés dans 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>

Votre appli TV est maintenant configurée pour s'exécuter en tant qu'expérience instantanée.

Préparer votre appli TV pour la publication

Consultez la checklist des applications TV pour connaître les prochaines étapes à suivre afin de préparer votre application TV en vue de sa publication et de sa distribution.