Créer et exécuter une application TV

Les applications Android TV utilisent la même structure que les applications sur téléphones et tablettes. Vous pouvez donc modifier vos applications existantes pour qu'elles fonctionnent sur les téléviseurs ou créer de nouvelles applications en vous appuyant sur ce que vous savez déjà sur la création d'applications pour Android.

Important : Pour pouvoir être désignée comme application Android TV sur Google Play, votre application doit respecter des exigences spécifiques. Pour en savoir plus, consultez les exigences listées dans la section Qualité des applications TV.

Ce guide explique comment préparer votre environnement de développement pour créer des applications TV et les modifications minimales requises pour qu'une application puisse s'exécuter sur les téléviseurs.

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

Déterminer la compatibilité avec les formats multimédias

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

Configurer un projet TV

Cette section explique comment configurer un projet TV, que vous modifiiez une application Android existante pour qu'elle s'exécute sur les téléviseurs ou que vous créiez une application TV. Si vous disposez d'une application Android existante, l'ajout de la compatibilité avec Android TV vous permet de concevoir une interface utilisateur pour les téléviseurs tout en réutilisant l'architecture de votre application existante.

Lorsque vous créez une application qui s'exécute sur les téléviseurs, vous utilisez deux composants principaux :

  • Activité pour les téléviseurs : dans le fichier manifeste de votre application, déclarez une activité destinée à s'exécuter sur les téléviseurs.
  • Bibliothèques TV : incluez éventuellement une ou plusieurs des bibliothèques androidx disponibles pour les téléviseurs, qui sont listées dans une autre section de ce guide. Ces bibliothèques fournissent des widgets pour créer des interfaces utilisateur.

Prérequis

Avant de commencer à créer une application pour les téléviseurs, vous devez suivre les étapes suivantes :

  • Mettez à jour vos outils SDK vers la version 24.0.0 ou ultérieure.
    Les outils SDK mis à jour vous permettent de créer et de tester des applications pour les téléviseurs.
  • Mettez à jour votre SDK avec Android 5.0 (API 21) ou version ultérieure.
    La version mise à jour de la plate-forme fournit de nouvelles API pour les applications TV.
  • Créez ou mettez à jour le projet de votre application.
    Pour accéder aux nouvelles API pour les téléviseurs, créez un projet ou modifiez un projet existant ciblant Android 5.0 (niveau d'API 21) ou version ultérieure.

Déclarer une activité TV

Une application destinée à s'exécuter sur les téléviseurs doit déclarer une activité de lanceur d'applications pour les téléviseurs dans son fichier manifeste. Pour ce faire, elle 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 comme une 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>

La deuxième entrée du fichier manifeste d'activité de cet exemple spécifie 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, les utilisateurs qui exécutent Google Play sur les téléviseurs ne pourront pas la voir. De plus, si votre application ne comporte pas ce filtre lorsque vous utilisez des outils de développement pour la charger sur un téléviseur, elle n'apparaît 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 à une distance de 3 mètres. Si vous modifiez une application existante pour l'utiliser sur un téléviseur, n'utilisez pas la même mise en page d'activité pour le téléviseur que celle que vous utilisez pour les téléphones et les tablettes. Pour obtenir des conseils sur la conception d'une application pour les téléviseurs, consultez la section Concevoir pour les téléviseurs.

Déclarer la compatibilité avec les téléviseurs

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

Si votre application s'exécute à la fois sur les appareils mobiles et les téléviseurs, 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 rendra votre application disponible que sur Android TV OS. 

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

Indiquer qu'aucun écran tactile n'est requis

Les applications destinées à s'exécuter sur les téléviseurs ne dépendent pas des écrans tactiles pour la saisie. Pour que cela soit clair, le fichier manifeste de votre application TV doit déclarer que la android.hardware.touchscreen fonctionnalité n'est pas requise. Ce paramètre identifie votre application comme étant compatible avec un téléviseur. Il est obligatoire pour que votre application soit considérée comme une application 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 d'application, vous devez déclarer qu'un écran tactile n'est pas requis, comme illustré dans cet exemple de code. Sinon, votre application n'apparaît 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 une icône 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 "Applications" et "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 fournir une icône sur l'écran d'accueil. Pour connaître les bonnes pratiques concernant la conception d'un point de lancement efficace pour votre application et les exigences détaillées concernant les éléments, consultez les consignes relatives aux icônes d'application et aux bannières des applications Android TV.

Utilisez l'attribut android:banner avec la balise <application> pour fournir une bannière par défaut pour toutes les activités de l'application, ou avec la balise <activity> pour 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. Le texte doit être inclus dans l'image. 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 : Sous Android 12 et versions ultérieures, les animations d'écran de démarrage personnalisées créées à l'aide de l' SplashScreen API de plate-forme ne sont pas compatibles avec les applications Android TV.

Lorsqu'une application TV est lancée, le système affiche une animation qui ressemble à un cercle plein en expansion. 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 illustré dans l'extrait suivant d'un fichier XML de ressource de thème :

<resources>
    <style name="MyTheme">
      <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 Android TV OS

Jetpack inclut des bibliothèques de packages androidx à utiliser avec les applications TV.

Compose pour la télévision

Nous vous recommandons d'utiliser Compose pour créer des applications pour Android TV OS. En plus des bibliothèques Compose principales, les bibliothèques Compose pour la télévision fournissent des composants dédiés spécialement conçus pour le grand écran :

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

Kit d'interface utilisateur Leanback

Le kit d'interface utilisateur Leanback fournit des API et des widgets d'interface utilisateur pour les téléviseurs :

Découvrez comment créer une application TV à l'aide du kit d'interface utilisateur Leanback dans la section Créer des applications de lecture TV.

Exécuter des applications TV

L'exécution de votre application est une étape 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 téléviseurs virtuels.

Exécuter 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, reportez-vous à la documentation fournie par le fabricant de votre appareil.
  2. Sur votre téléviseur, accédez à Paramètres.
  3. Dans la ligne Appareil, sélectionnez À propos.
  4. Faites défiler l'écran jusqu'à Build , puis sélectionnez Build plusieurs fois jusqu'à ce que le message "Vous êtes désormais développeur !" s'affiche.
  5. Revenez à Paramètres. Dans 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 Exécuter dans la barre d'outils.
  2. Dans la fenêtre Sélectionner une cible de déploiement , sélectionnez votre téléviseur, puis cliquez sur OK.

Exécuter sur un appareil virtuel

AVD Manager dans le SDK Android fournit des définitions d'appareils qui vous permettent de créer des téléviseurs virtuels pour exécuter et tester vos applications.

Pour créer un téléviseur virtuel :

  1. Démarrez AVD Manager. Pour en savoir plus, consultez la section Créer et gérer des appareils virtuels.
  2. Dans la boîte de dialogue AVD Manager, cliquez sur l'onglet Définitions d'appareils.
  3. Sélectionnez l'une des définitions d'appareils 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 de téléviseur, utilisez l'émulateur x86 et activez l'option Utiliser le GPU hôte. Utilisez également l'accélération des appareils virtuels lorsqu'elle est disponible. Pour en savoir plus sur l'accélération matérielle de l'émulateur, consultez la section Configurer l'accélération matérielle pour Android Emulator.

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

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

Pour en savoir plus sur l'utilisation des émulateurs, consultez la section Exécuter des applications sur Android Emulator. Pour en savoir plus sur le déploiement d'applications d'Android Studio sur des appareils virtuels, consultez la section 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 son adoption.

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

Ensuite, dans le intent-filter de la 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 application TV est désormais configurée pour s'exécuter en tant qu'expérience instantanée.

Préparer la publication de votre application TV

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

Suivant
Gérer le matériel TV