Gérer le matériel TV

Le matériel TV est très différent de celui des autres appareils Android. Les téléviseurs n'incluent pas certaines des fonctionnalités matérielles présentes sur d'autres appareils Android, telles que les écrans tactiles, les appareils photo et les récepteurs GPS. Les téléviseurs dépendent également entièrement des appareils matériels secondaires : pour que les utilisateurs interagissent avec les applications TV, ils doivent utiliser une télécommande ou une manette de jeu. (Pour en savoir plus sur les différentes méthodes de saisie, consultez Gérer les télécommandes TV.)

Lorsque vous créez une application pour la TV, tenez compte des limites et des exigences matérielles liées à son fonctionnement sur le matériel TV. Vérifiez si votre application s'exécute sur un téléviseur et gérez les fonctionnalités matérielles non compatibles.

Rechercher un appareil TV

Si vous créez une application qui fonctionne à la fois sur des appareils TV et d'autres appareils, vous devrez peut-être vérifier le type d'appareil sur lequel votre application s'exécute et ajuster son fonctionnement. Par exemple, si vous disposez d'une application qui peut être lancée via un Intent, vérifiez les propriétés de l'appareil pour déterminer s'il faut démarrer une activité orientée TV ou une activité téléphonique.

Pour déterminer si votre application s'exécute sur un appareil TV, nous vous recommandons d'utiliser la méthode PackageManager.hasSystemFeature() afin de vérifier si l'appareil est en mode TV. L'exemple de code suivant montre comment vérifier si votre application s'exécute sur un appareil TV :

Kotlin

const val TAG = "DeviceTypeRuntimeCheck"

val isTelevision = packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK)
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device")
} else {
    Log.d(TAG, "Running on a non-TV Device")
}
Hardware.kt

Java

public static final String TAG = "DeviceTypeRuntimeCheck";

boolean isTelevision = getPackageManager().hasSystemFeature(PackageManager.FEATURE_LEANBACK);
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device");
} else {
    Log.d(TAG, "Running on a non-TV Device");
}

Gérer les fonctionnalités matérielles non compatibles

En fonction de la conception et des fonctionnalités de votre application, vous pourrez peut-être contourner l'indisponibilité de certaines fonctionnalités matérielles. Cette section explique quelles fonctionnalités matérielles ne sont généralement pas disponibles pour la TV, comment détecter les fonctionnalités matérielles manquantes et quelles alternatives sont suggérées pour ces fonctionnalités.

Fonctionnalités matérielles TV non compatibles

Les téléviseurs ont un objectif différent des autres appareils. Ils ne disposent donc pas des fonctionnalités matérielles que les autres appareils Android possèdent souvent. Pour cette raison, le système Android n'est pas compatible avec les fonctionnalités suivantes pour un appareil TV :

Matériel	Descripteur de fonctionnalité Android
Écran tactile	android.hardware.touchscreen
Émulateur d'écran tactile	android.hardware.faketouch
Téléphonie	android.hardware.telephony
Appareil photo	android.hardware.camera
Technologie NFC (communication en champ proche)	android.hardware.nfc
GPS	android.hardware.location.gps
Micro	android.hardware.microphone
Capteurs	android.hardware.sensor
Écran en mode portrait	android.hardware.screen.portrait

Remarque : Certaines télécommandes TV sont équipées d'un micro, qui n'est pas la même chose que la fonctionnalité matérielle de micro décrite ici. Le micro de la télécommande est entièrement compatible.

Consultez la documentation de référence sur les fonctionnalités pour obtenir la liste complète des fonctionnalités, des sous-fonctionnalités et de leurs descripteurs.

Indiquer la configuration matérielle requise pour le téléviseur

Les applications Android peuvent déclarer des exigences de fonctionnalités matérielles dans le fichier manifeste d'application pour s'assurer qu'elles ne sont pas installées sur des appareils qui ne fournissent pas ces fonctionnalités. Si vous étendez une application existante pour l'utiliser sur un téléviseur, examinez attentivement le fichier manifeste de votre application pour détecter toute déclaration d'exigence matérielle qui pourrait empêcher son installation sur un appareil TV.

Si votre application utilise des fonctionnalités matérielles telles qu'un écran tactile ou un appareil photo qui ne sont pas disponibles sur un téléviseur, mais qu'elle peut fonctionner sans ces fonctionnalités, modifiez le fichier manifeste de votre application pour indiquer que ces fonctionnalités ne sont pas requises. L'extrait de code de fichier manifeste suivant montre comment déclarer que votre application ne nécessite pas de fonctionnalités matérielles qui ne sont pas disponibles sur les appareils TV, mais qu'elle les utilise sur des appareils non TV :

<uses-feature android:name="android.hardware.touchscreen"
        android:required="false"/>
<uses-feature android:name="android.hardware.faketouch"
        android:required="false"/>
<uses-feature android:name="android.hardware.telephony"
        android:required="false"/>
<uses-feature android:name="android.hardware.camera"
        android:required="false"/>
<uses-feature android:name="android.hardware.nfc"
        android:required="false"/>
<uses-feature android:name="android.hardware.location.gps"
        android:required="false"/>
<uses-feature android:name="android.hardware.microphone"
        android:required="false"/>
<uses-feature android:name="android.hardware.sensor"
        android:required="false"/>
<!-- Some TV devices have an ethernet connection only -->
<uses-feature android:name="android.hardware.wifi"
        android:required="false"/>

Remarque : Certaines fonctionnalités comportent des sous-fonctionnalités, comme android.hardware.camera.front, comme décrit dans la documentation de référence sur les fonctionnalités. Veillez à marquer toutes les sous-fonctionnalités également utilisées dans votre application comme required="false".

Toutes les applications destinées à être utilisées sur des appareils TV doivent déclarer que la fonctionnalité d'écran tactile n'est pas requise, comme décrit dans Premiers pas avec les applications TV. Si votre application utilise normalement une ou plusieurs des fonctionnalités non compatibles avec les appareils TV, remplacez le android:required paramètre d'attribut par false pour ces fonctionnalités dans votre fichier manifeste.

Attention : Si vous déclarez une fonctionnalité matérielle comme requise en définissant sa valeur sur true , votre application ne pourra pas être installée sur les appareils TV ni apparaître dans le lanceur de l'écran d'accueil Android TV.

Tenir compte des autorisations qui impliquent des fonctionnalités matérielles

Certaines uses-permission déclarations de fichier manifeste impliquent des fonctionnalités matérielles. Cela signifie que le fait de demander certaines autorisations dans le fichier manifeste d'application de votre application peut empêcher son installation et son utilisation sur les appareils TV. Les autorisations couramment demandées suivantes créent une exigence implicite de fonctionnalité matérielle :

Autorisation	Fonctionnalité matérielle implicite
RECORD_AUDIO	android.hardware.microphone
CAMERA	android.hardware.camera et android.hardware.camera.autofocus
ACCESS_COARSE_LOCATION	android.hardware.location android.hardware.location.network (niveau d'API cible 20 ou inférieur uniquement)
ACCESS_FINE_LOCATION	android.hardware.location android.hardware.location.gps (niveau d'API cible 20 ou inférieur uniquement)
ACCESS_WIFI_STATE CHANGE_WIFI_STATE	android.hardware.wifi Certains appareils TV ne disposent que d'une connexion Ethernet.

Pour obtenir la liste complète des demandes d'autorisation qui impliquent une exigence de fonctionnalité matérielle, consultez le uses-feature guide. Si votre application demande l'une des fonctionnalités listées précédemment, incluez une uses-feature déclaration dans votre fichier manifeste pour la fonctionnalité matérielle implicite qui indique qu'elle n'est pas requise. android:required="false".

Remarque : Si votre application cible Android 5.0 (niveau d'API 21) ou une version ultérieure, et qu'elle utilise l'autorisation ACCESS_COARSE_LOCATION ou ACCESS_FINE_LOCATION, les utilisateurs peuvent toujours installer votre application sur un appareil TV, même si celui-ci ne dispose pas de carte réseau ni de récepteur GPS.

Une fois que vous avez rendu les fonctionnalités matérielles facultatives pour votre application, vous devez vérifier la disponibilité de ces fonctionnalités au moment de l'exécution, puis ajuster le comportement de votre application. La section suivante explique comment vérifier les fonctionnalités matérielles et suggère quelques approches pour modifier le comportement de votre application.

Pour en savoir plus sur le filtrage et la déclaration de fonctionnalités dans le fichier manifeste, consultez le uses-feature guide.

Vérifier les fonctionnalités matérielles

Le framework Android peut vous indiquer si les fonctionnalités matérielles ne sont pas disponibles sur l'appareil sur lequel votre application s'exécute. Utilisez la méthode hasSystemFeature(String) pour vérifier des fonctionnalités spécifiques au moment de l'exécution. Cette méthode accepte un seul argument de chaîne qui spécifie la fonctionnalité que vous souhaitez vérifier.

L'exemple de code suivant montre comment détecter la disponibilité des fonctionnalités matérielles au moment de l'exécution :

Kotlin

// Check whether the telephony hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls")
}

// Check whether android.hardware.touchscreen feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.")
}
Hardware.kt

Java

// Check whether the telephony hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls");
}

// Check whether android.hardware.touchscreen feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.");
}

Écran tactile

La plupart des appareils TV ne disposent pas d'écran tactile ni de capacités de saisie par pointeur, et dépendent entièrement des télécommandes à pavé directionnel pour la navigation. Les applications TV doivent toujours être compatibles avec une télécommande à pavé directionnel.

Pour en savoir plus sur la prise en charge appropriée de la navigation à l'aide de commandes adaptées à la TV, consultez Navigation TV.

Déclarer la prise en charge du mode tactile

Certains appareils TV sont compatibles avec les télécommandes à pointeur et les écrans tactiles. Votre application peut prendre en charge les interactions de clic, de survol et de défilement, comme sur un appareil mobile, pour offrir une meilleure expérience sur les appareils compatibles.

Si votre application autorise le mode tactile, vous pouvez déclarer la prise en charge du mode tactile en ajoutant android.software.leanback.supports_touch défini sur true dans votre AndroidManifest.xml :

<meta-data android:name="android.software.leanback.supports_touch" android:value="true|false"/>

Remarque : Sur les appareils compatibles avec une télécommande à pointeur (comme une souris sans fil ou un pavé tactile), l'activation de cette option permet d'utiliser le mode curseur et tactile plutôt que de s'appuyer sur l'émulation de compatibilité de la plate-forme. Si vous omettez ces métadonnées, la valeur par défaut est false.

Appareil photo

Bien qu'un téléviseur ne dispose généralement pas d'appareil photo, vous pouvez toujours proposer une application liée à la photographie sur un téléviseur. Par exemple, si vous disposez d'une application qui prend, affiche et modifie des photos, vous pouvez désactiver sa fonctionnalité de prise de photos pour les téléviseurs et permettre aux utilisateurs de visualiser et même de modifier des photos. Si vous décidez d'activer votre application liée à l'appareil photo sur un téléviseur, ajoutez la déclaration de fonctionnalité suivante dans le fichier manifeste de votre application :

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

Si vous activez l'exécution de votre application sans appareil photo, ajoutez du code à votre application qui détecte si la fonctionnalité d'appareil photo est disponible et ajuste le fonctionnement de votre application. L'exemple de code suivant montre comment détecter la présence d'un appareil photo :

Kotlin

// Check whether the camera hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!")
} else {
    Log.d("Camera test", "No camera available. View and edit features only.")
}
Hardware.kt

Java

// Check whether the camera hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!");
} else {
    Log.d("Camera test", "No camera available. View and edit features only.");
}

GPS

Les téléviseurs sont des appareils fixes d'intérieur et ne disposent pas de récepteurs GPS (Global Positioning System) intégrés. Si votre application utilise des informations de localisation, vous pouvez toujours permettre aux utilisateurs de rechercher un lieu ou d'utiliser un fournisseur de localisation statique, tel qu'un code postal configuré lors de la configuration de l'appareil TV.

Kotlin

// Request a static location from the location manager.
val locationManager = this.getSystemService(Context.LOCATION_SERVICE) as LocationManager
val location = locationManager.getLastKnownLocation("static")
if (location == null) {
    Log.e(TAG, "Location is null")
    return
}

// Attempt to get postal code from the static location object.
val geocoder = Geocoder(this)
val address: Address? =
        try {
            geocoder.getFromLocation(location.latitude, location.longitude, 1)?.firstOrNull()
                    ?.apply {
                        Log.d(TAG, postalCode)
                    }
        } catch (e: IOException) {
            Log.e(TAG, "Geocoder error", e)
            null
        }
Hardware.kt

Java

// Request a static location from the location manager.
LocationManager locationManager = (LocationManager) this.getSystemService(
        Context.LOCATION_SERVICE);
Location location = locationManager.getLastKnownLocation("static");

// Attempt to get postal code from the static location object.
Geocoder geocoder = new Geocoder(this);
Address address = null;
try {
  address = geocoder.getFromLocation(location.getLatitude(),
          location.getLongitude(), 1).get(0);
  Log.d("Postal code", address.getPostalCode());

} catch (IOException e) {
  Log.e(TAG, "Geocoder error", e);
}

Mettre en pause la lecture en mode basse consommation

Certains appareils TV sont compatibles avec un mode basse consommation lorsque l'utilisateur éteint l'appareil. Au lieu de s'éteindre, l'appareil désactive l'écran et maintient Android TV en arrière-plan. La sortie audio est toujours activée dans ce mode. Arrêtez donc tout contenu en cours de lecture lorsque l'appareil est en mode basse consommation.

Pour éviter la lecture en mode basse consommation, remplacez onStop() et arrêtez tout contenu en cours de lecture :

Kotlin

override fun onStop() {
    // App-specific method to stop playback.
    stopPlayback()
    super.onStop()
}

Java

@Override
public void onStop() {
  // App-specific method to stop playback.
  stopPlayback();
  super.onStop();
}

Lorsque l'utilisateur rallume l'appareil, onStart() est appelé si votre application est l'application au premier plan active. Pour en savoir plus sur le démarrage et l'arrêt d'une activité, consultez le cycle de vie d'une activité.