Créer et exécuter une application 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 appareils TV ou créer de nouvelles applications 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 listées dans Qualité des applis TV.

Ce guide explique comment préparer votre environnement de développement pour créer des applications TV et décrit les modifications minimales requises pour permettre à une application de s'exécuter sur des appareils TV.

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

Déterminer la compatibilité des formats multimédias

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

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

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 des appareils TV ou que vous créiez une application TV. Si vous disposez d'une application Android existante, l'ajout de la prise en charge d'Android TV vous permet de concevoir une interface utilisateur pour la TV tout en réutilisant l'architecture de votre application existante.

Lorsque vous créez une application qui s'exécute sur des appareils TV, vous utilisez deux composants principaux :

• Activité pour TV : dans le fichier manifeste de votre application, déclarez une activité destinée à s'exécuter sur des appareils TV.
• Bibliothèques TV : incluez éventuellement une ou plusieurs des bibliothèques androidx disponibles pour les appareils TV, 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 téléviseur, 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 téléviseur.
• 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 appareils TV, créez un projet ou modifiez un projet existant qui cible Android 5.0 (niveau d'API 21) ou version ultérieure.

Déclarer une activité TV

Une application destinée à s'exécuter sur des appareils TV doit déclarer une activité de lanceur d'applications pour TV dans son fichier manifeste. Pour ce faire, il utilise un filtre d'intent CATEGORY_LEANBACK_LAUNCHER. Ce filtre indique que votre application est activée pour la TV 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 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, les utilisateurs qui exécutent Google Play sur des téléviseurs ne pourront pas la voir. De plus, si votre application ne comporte pas ce filtre lorsque vous utilisez des outils pour les développeurs 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 permettre une navigation intuitive à l'aide d'une télécommande à trois mètres de distance. 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 pour les téléphones et les tablettes. Pour obtenir des consignes sur la conception d'une application pour téléviseur, consultez Concevoir une application pour téléviseur.

Déclarer la compatibilité avec les appareils TV

Indiquez 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 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 des appareils TV ne s'appuient pas sur les écrans tactiles pour la saisie. Pour que cela soit clair, le fichier manifeste de votre application TV doit déclarer que la fonctionnalité android.hardware.touchscreen n'est pas requise. Ce paramètre indique que votre application peut fonctionner sur un téléviseur. Il est obligatoire pour que votre application soit considérée comme une application TV sur 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 indiqué dans cet exemple de code. Sinon, votre application n'apparaîtra pas sur Google Play sur les appareils TV.

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

Les applications Android TV doivent fournir une icône d'é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 s'affiche 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

Comme toutes les applications Android, les applications Android TV doivent fournir une icône pour l'écran d'accueil. Pour découvrir les bonnes pratiques concernant la conception d'un point de lancement efficace pour votre application et les exigences détaillées concernant les composants, consultez les consignes relatives aux icônes d'application et aux bannières des applis Android TV.

Bannière de l'écran d'accueil

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. L'image doit contenir 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 acceptée.

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'API de plate-forme SplashScreen ne sont pas compatibles avec les applications Android TV.

Lorsqu'une appli TV se lance, le système affiche une animation qui ressemble à un cercle plein qui s'agrandit. 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 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>
create.xml

Pour en savoir plus sur l'utilisation des thèmes et des styles, consultez 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

Compose est la méthode recommandée pour créer des applications pour Android TV OS. En plus des bibliothèques Compose principales, les bibliothèques Compose pour TV fournissent des composants dédiés spécialement conçus pour les grands écrans :

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

Découvrez comment créer une application TV à l'aide de Compose for TV dans 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 :

• 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'UI Leanback dans 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 appareil TV à 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. Dans la ligne Appareil, sélectionnez À propos.
4. Faites défiler l'écran jusqu'à Build (Compilation), puis sélectionnez Build (Compiler) plusieurs fois jusqu'à ce que le message "Vous êtes désormais un développeur !" s'affiche.
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'appareils qui vous permettent de créer des appareils TV virtuels pour exécuter et tester vos applications.

Pour créer un appareil TV virtuel :

1. Démarrez AVD Manager. Pour en savoir plus, consultez 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 Create AVD (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 Utiliser le GPU hôte. Utilisez également l'accélération de l'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 TV virtuel :

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 TV virtuel, 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 depuis Android Studio vers 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 votre application TV sans l'installer, ce qui peut contribuer à augmenter son 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, commencez par suivre les instructions pour créer un app bundle compatible avec les applications instantanées.

Ensuite, dans le intent-filter du MainActivity de votre appli 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 maintenant configurée pour s'exécuter en tant qu'expérience instantanée.

Préparer votre application TV pour la publication

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