Gérer les télécommandes de téléviseur

Les appareils TV nécessitent un appareil matériel secondaire pour interagir avec les applications : une télécommande de base, une télécommande avec pointeur ou une manette de jeu. Pour offrir une expérience utilisateur cohérente, votre application doit prendre en charge la saisie au pavé directionnel, gérer la déconnexion des manettes et accepter la saisie à partir de plusieurs types de manettes, y compris les télécommandes pointeur.

Commandes minimales du pavé directionnel

Le contrôleur par défaut d'un téléviseur est un pavé directionnel. En général, votre application doit être utilisable avec une télécommande qui ne comporte que les boutons Haut, Bas, Gauche, Droite, Sélectionner, Retour et Accueil. Si votre application est un jeu qui nécessite généralement une manette avec des commandes supplémentaires, essayez de permettre aux utilisateurs de jouer uniquement avec les commandes du pavé directionnel. Sinon, avertissez l'utilisateur qu'une manette est requise et laissez-le quitter votre jeu de manière élégante à l'aide du pavé directionnel.

Pour en savoir plus sur la navigation avec des pavés directionnels pour les appareils TV, consultez Navigation TV.

Gérer les déconnexions du contrôleur

Les télécommandes pour téléviseur sont souvent des appareils Bluetooth qui peuvent tenter d'économiser de l'énergie en se mettant périodiquement en veille et en se déconnectant du téléviseur. Cela signifie qu'une application peut être interrompue ou redémarrée si elle n'est pas configurée pour gérer ces événements de reconnexion. Ces événements peuvent se produire dans les circonstances suivantes :

• Pendant la lecture d'une vidéo de plusieurs minutes, il est possible qu'un pavé directionnel ou une manette de jeu se mettent en veille, se déconnectent de l'appareil TV, puis se reconnectent plus tard.
• Pendant le jeu, un nouveau joueur peut rejoindre la partie à l'aide d'une manette de jeu qui n'est pas encore connectée.
• Pendant le jeu, un joueur peut quitter le jeu et déconnecter une manette de jeu.

Toute activité d'application TV soumise à des événements de déconnexion et de reconnexion doit être configurée pour gérer les événements de reconnexion dans le fichier manifeste d'application. L'exemple de code suivant montre comment permettre à une activité de gérer les changements de configuration, y compris la connexion, la déconnexion ou la reconnexion d'un clavier ou d'un dispositif de navigation :

<activity
  android:name="com.example.android.TvActivity"
  android:label="@string/app_name"
  android:configChanges="keyboard|keyboardHidden|navigation"
  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>

Cette modification de la configuration permet à l'application de continuer à s'exécuter lors d'un événement de reconnexion, au lieu d'être redémarrée par le framework Android, ce qui n'est pas une bonne expérience utilisateur.

Gérer les variations de saisie au pavé directionnel

Les utilisateurs de téléviseurs peuvent utiliser plusieurs types de télécommandes avec leur téléviseur. Par exemple, un utilisateur peut disposer d'une manette à pavé directionnel de base, d'une télécommande pointeur ou d'une manette de jeu. Les codes de touche fournis par une manette de jeu lorsqu'elle est utilisée pour les fonctions du pavé directionnel peuvent varier par rapport aux codes de touche envoyés par un pavé directionnel de base.

Gérez les variations de saisie du pavé directionnel afin que l'utilisateur n'ait pas à changer de manette pour utiliser votre application. Pour en savoir plus sur la gestion des variations de saisie, consultez Traiter les saisies du pavé directionnel.

Compatibilité avec les télécommandes pointeur

Certains appareils TV sont compatibles avec les télécommandes pointeur, comme les télécommandes gyroscopiques ou celles dotées de pavés directionnels tactiles (trackpads). La prise en charge des télécommandes avec pointeur permet aux utilisateurs d'interagir avec votre application à l'aide de gestes pointer-cliquer, pointer sur, balayer et faire glisser. Ils bénéficient ainsi d'une expérience plus fluide sur le matériel compatible, tout en conservant une compatibilité totale avec le pavé directionnel.

Déclarer la prise en charge du pointeur de télécommande dans le fichier manifeste

Pour indiquer que votre application est navigable avec un pointeur et une entrée tactile, configurez le fichier manifeste de votre application avec les métadonnées android.software.leanback.supports_touch définies sur true :

<manifest ...>
    <!-- Signal whether the app is adaptive or built just for TV -->
    <uses-feature
        android:name="android.software.leanback"
        android:required="true|false" />
    <!-- Ensure the app can be installed on conventional TVs -->
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <!-- Signal whether the app supports pointer remotes -->
    <meta-data
        android:name="android.software.leanback.supports_touch"
        android:value="true" />
    <application ...>
        ...
    </application>
</manifest>

Prise en charge des interactions de clic, de pointage et de défilement

Lorsque vous prenez en charge les télécommandes avec pointeur, assurez-vous que vos composants d'UI répondent de manière appropriée aux entrées au curseur et tactiles pour les interactions suivantes :

• Cliquer et sélectionner : tous les éléments d'UI sélectionnables et sur lesquels il est possible de se concentrer doivent être cliquables avec la télécommande pointeur, comme avec la sélection au pavé directionnel (KEYCODE_DPAD_CENTER).
  • Jetpack Compose : utilisez les modificateurs Modifier.clickable() ou pointerInput. Pour en savoir plus, consultez Appuyer et appuyer de manière prolongée.
  • Views : gère les événements de clic sur les vues. Pour en savoir plus, consultez Présentation des événements d'entrée.
• Les états visuels de survol fournissent un effet visuel clair pour indiquer quand le curseur du pointeur est positionné sur un élément sélectionnable.
  • Jetpack Compose : utilisez Modifier.hoverable() ou observez les états de survol à l'aide d'un InteractionSource. Pour en savoir plus, consultez Gérer les interactions utilisateur.
  • Vues : définissez les états de survol à l'aide de drawables de liste d'états avec android:state_hovered="true".
• Défilement par balayage et défilement rapide : le défilement horizontal et vertical déclenché par un geste de balayage ou de défilement rapide sur un bouton central du pavé directionnel tactile doit fonctionner de manière fluide sur tous les contenus pouvant être parcourus.
• Défilement par glissement : les utilisateurs doivent pouvoir faire glisser l'écran pour le faire défiler verticalement (vers le haut et vers le bas) ou horizontalement (vers la gauche et vers la droite) dans les conteneurs à défilement.
  • Jetpack Compose : les conteneurs à défilement standards sont compatibles avec le défilement au pointeur et tactile par défaut. Pour les implémentations personnalisées, consultez Saisie avec un dispositif de pointage dans Compose.
  • Vues : les vues déroulantes standards sont compatibles avec le défilement tactile par défaut. Pour la gestion des entrées personnalisées, consultez Saisie tactile et entrées.
• Lecture de contenu multimédia : pendant la lecture de contenu multimédia (comme des séries TV et des films), les utilisateurs doivent pouvoir interagir avec la barre de progression de la lecture (barre de recherche) en pointant et en cliquant pour accéder à un code temporel passé ou futur, ainsi qu'en faisant glisser (en parcourant) la barre de progression pour accéder à un moment précis.

Gérer les événements de bouton

Lorsque l'utilisateur clique sur un bouton de la manette, votre application reçoit un événement avec un KeyEvent. Le comportement attendu du bouton peut être un événement multimédia (lecture, pause ou arrêt, par exemple) ou un événement de type TV (sélection ou navigation, par exemple). Pour offrir une bonne expérience utilisateur, attribuez un comportement cohérent aux boutons de la manette.

Événements de l'UI TV

Attribuez le comportement de l'UI TV aux boutons qui génèrent des types KeyEvent, comme indiqué dans le tableau suivant :

Événements multimédias

Lorsque l'utilisateur regarde un contenu multimédia, attribuez un comportement aux boutons qui génèrent des types KeyEvent, comme indiqué dans le tableau suivant. Si votre application contrôle un MediaSession, utilisez un MediaControllerAdapter pour appeler l'une des méthodes MediaControllerCompat.TransportControls indiquées dans le tableau. Notez que les boutons de sélection agissent comme des boutons de lecture ou de pause dans ce contexte.

Fournir un comportement approprié pour le bouton "Retour"

Le bouton "Retour" ne doit jamais servir de bouton bascule. Par exemple, ne l'utilisez pas à la fois pour ouvrir et fermer un menu. Utilisez-le uniquement pour revenir en arrière, comme un fil d'Ariane, dans les écrans précédents sur lesquels le lecteur s'est trouvé.

Étant donné que le bouton Retour ne permet qu'une navigation linéaire vers l'arrière, vous pouvez l'utiliser pour quitter un menu intégré à l'application ouvert par un autre bouton et revenir à l'application. Appuyer plusieurs fois de suite sur le bouton Retour doit toujours finir par vous ramener à l'écran d'accueil d'Android TV. Par exemple : gameplay > écran de pause du jeu > écran principal du jeu > écran d'accueil d'Android TV ou lecture d'un programme TV > écran principal de l'appli TV

Écran d'accueil Android TV.

Pour en savoir plus sur la conception de la navigation, consultez Concevoir la navigation "Retour" et "Haut". Pour en savoir plus sur l'implémentation, consultez Fournir un retour en arrière approprié.

Prise en main des manettes de jeu

Lorsque vous créez des jeux pour Android TV, concevez votre système de commandes pour qu'il fonctionne à la fois avec les télécommandes TV standards et les manettes de jeu dédiées.

Prise en charge des commandes par pavé directionnel

Planifiez votre schéma de contrôle autour d'un pavé directionnel, car cet ensemble de commandes est celui par défaut pour les appareils Android TV. Le joueur doit pouvoir utiliser un pavé directionnel pour tous les aspects du jeu, et pas seulement pour contrôler le gameplay de base, mais aussi pour parcourir les menus et les annonces. Pour cette raison, assurez-vous que votre jeu Android TV ne fait pas référence à une interface tactile avec des expressions telles que "Appuyez ici pour continuer".

La façon dont vous façonnez l'interaction du joueur avec la manette peut être essentielle pour offrir une expérience utilisateur optimale. Voici quelques bonnes pratiques :

• Communiquez les exigences concernant les manettes à l'avance : utilisez la description de votre jeu sur Google Play pour informer le joueur des attentes concernant les manettes. Si un jeu est plus adapté à une manette de jeu avec un joystick qu'à une manette avec uniquement un pavé directionnel, indiquez-le clairement. Un joueur qui utilise une manette inadaptée à un jeu peut avoir une mauvaise expérience et donner une mauvaise note à votre jeu.
• Utilisez un mappage des boutons cohérent : un mappage intuitif des boutons est essentiel pour une bonne expérience utilisateur. Par exemple, respectez les conventions acceptées en utilisant le bouton A pour accepter et le bouton B pour annuler. Vous pouvez également offrir de la flexibilité en permettant à l'utilisateur de remapper les boutons. Pour en savoir plus sur le mappage des boutons, consultez Gérer les actions de la manette.
• Détectez les capacités de la manette et ajustez-les en conséquence : interrogez la manette sur ses capacités pour optimiser la compatibilité entre la manette et le jeu. Par exemple, vous pouvez vouloir qu'un joueur dirige un objet en agitant la manette dans les airs, mais si la manette d'un joueur ne dispose pas d'un accéléromètre et d'un gyroscope, l'agitation ne fonctionne pas. Interrogez le contrôleur et, si la détection de mouvement n'est pas prise en charge, passez à un autre schéma de contrôle disponible. Pour en savoir plus sur l'interrogation des capacités du contrôleur, consultez Prendre en charge les contrôleurs sur les différentes versions d'Android.

Utiliser les boutons appropriés

Toutes les manettes de jeu ne sont pas dotées des boutons "Démarrer", "Rechercher" ou "Menu". Assurez-vous que votre UI ne dépend pas de l'utilisation de ces boutons.

Gérer plusieurs contrôleurs

Lorsque plusieurs joueurs jouent à un jeu, chacun avec sa propre manette, il est important de mapper chaque paire joueur-manette. Pour savoir comment implémenter l'identification du numéro de contrôleur, consultez getControllerNumber().

Gérer les déconnexions du contrôleur

Lorsqu'une manette est déconnectée en cours de partie, mettez le jeu en pause et affichez une boîte de dialogue invitant le joueur déconnecté à reconnecter sa manette.

Proposez également des conseils de dépannage dans la boîte de dialogue. Par exemple, dites au lecteur "Vérifiez votre connexion Bluetooth". Pour en savoir plus sur l'implémentation de la prise en charge des périphériques d'entrée, consultez Gérer les actions de la manette et la présentation de Bluetooth.

Afficher les instructions de la manette

Si votre jeu fournit des instructions visuelles pour les commandes, utilisez une image de manette sans marque et n'incluez que les boutons compatibles avec Android.

Pour obtenir des exemples d'images d'une manette compatible avec Android, téléchargez le modèle de gamepad Android TV (ZIP). Il inclut une manette blanche sur un fond noir et une manette noire sur un fond blanc (voir figure 1), au format PNG et Adobe® Illustrator®.