Gérer le matériel TV

Le matériel des téléviseurs est sensiblement différent de celui des autres appareils Android. Les téléviseurs n'incluent pas certaines des fonctionnalités matérielles disponibles sur d'autres appareils Android, telles que les écrans tactiles, les caméras et les récepteurs GPS. Les téléviseurs dépendent également entièrement d'appareils matériels secondaires : pour que les utilisateurs puissent interagir 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 manettes de jeu pour téléviseur.)

Lorsque vous créez une application pour la télévision, tenez compte des limites matérielles et des exigences liées à l'utilisation du 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 téléviseur

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

Pour déterminer si votre application s'exécute sur un téléviseur, nous vous recommandons d'utiliser la méthode PackageManager.hasSystemFeature pour vérifier si l'appareil fonctionne en mode télévision. L'exemple de code suivant montre comment vérifier si votre application s'exécute sur un téléviseur :

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

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

Fonctionnalités matérielles TV non compatibles

Les téléviseurs ont un objectif différent de celui des autres appareils. Ils ne disposent donc pas des fonctionnalités matérielles que l'on trouve souvent sur les autres appareils Android. C'est pourquoi le système Android n'est pas compatible avec les fonctionnalités suivantes pour un téléviseur :

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 de téléviseur sont équipées d'un micro, qui n'est pas le même que la fonctionnalité matérielle de micro décrite ici. Le micro de la manette est entièrement compatible.

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

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

Les applications Android peuvent déclarer les exigences matérielles dans le fichier manifeste de l'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 susceptible d'empêcher son installation sur un téléviseur.

Si votre application utilise des fonctionnalités matérielles (telles qu'un écran tactile ou un appareil photo) qui ne sont pas disponibles sur TV, mais qu'elle peut fonctionner sans utiliser ces fonctionnalités, modifiez son fichier manifeste pour indiquer qu'elles ne sont pas nécessaires. L'extrait de code de fichier manifeste suivant montre comment déclarer que votre application n'a pas besoin de fonctionnalités matérielles qui ne sont pas disponibles sur les téléviseurs, mais qu'elle les utilise sur d'autres appareils :

<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 ont 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 comme required="false" toutes les sous-fonctionnalités également utilisées dans votre application.

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 téléviseurs, définissez l'attribut android:required sur 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 téléviseurs ni apparaître dans le lanceur d'applications de l'écran d'accueil d'Android TV.

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

Certaines déclarations de fichier manifeste uses-permission impliquent des fonctionnalités matérielles. Ce comportement signifie que la demande de certaines autorisations dans le fichier manifeste de votre application peut empêcher l'installation et l'utilisation de votre application sur les téléviseurs. Les autorisations suivantes, couramment demandées, créent une exigence de fonctionnalité matérielle implicite :

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 inférieur ou égal à 20 uniquement)
ACCESS_FINE_LOCATION	android.hardware.location android.hardware.location.gps (niveau d'API cible inférieur ou égal à 20 uniquement)
ACCESS_WIFI_STATE CHANGE_WIFI_STATE	android.hardware.wifi Certains téléviseurs 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 guide uses-feature. Si votre application demande l'une des fonctionnalités listées précédemment, incluez une déclaration uses-feature dans votre fichier manifeste pour la fonctionnalité matérielle implicite, indiquant 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 l'installer sur un téléviseur, même si celui-ci ne dispose pas d'une carte réseau ou d'un récepteur GPS.

Après avoir rendu les fonctionnalités matérielles facultatives pour votre application, vous devez vérifier leur disponibilité 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 des approches pour modifier le comportement de votre application.

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

Vérifier les fonctionnalités matérielles

Le framework Android peut vous indiquer si des fonctionnalités matérielles ne sont pas disponibles sur l'appareil sur lequel votre application est exécutée. 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 téléviseurs ne disposent pas d'écrans tactiles ni de fonctionnalités de saisie par pointeur, et s'appuient entièrement sur les 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 de la navigation à l'aide de commandes adaptées aux téléviseurs, consultez Navigation sur un téléviseur.

Déclarer la compatibilité avec l'écran tactile

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

Si votre application autorise le mode tactile, vous pouvez déclarer la compatibilité tactile pour l'ensemble de l'application ou pour des activités individuelles en ajoutant l'élément android.software.leanback.supports_touch <property> défini sur true dans l'élément <application> ou <activity> de votre AndroidManifest.xml :

<application ...>
    <property
        android:name="android.software.leanback.supports_touch"
        android:value="true|false" />
    ...
</application>

Remarque : Sur les appareils compatibles avec une télécommande de pointage (comme une souris gyroscopique ou un pavé tactile), l'activation de cette option active le curseur et le mode tactile au lieu de s'appuyer sur l'émulation de compatibilité de la plate-forme. Une déclaration au niveau de l'activité remplace la déclaration au niveau de l'application pour cette activité. Si vous omettez cette propriété, la valeur par défaut est false.

Appareil photo

Bien qu'un téléviseur ne soit généralement pas équipé d'un appareil photo, vous pouvez toujours proposer une application de 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 vue pour les téléviseurs, tout en permettant aux utilisateurs d'afficher et même de modifier des photos. Si vous décidez d'activer votre application liée à l'appareil photo pour qu'elle fonctionne sur un téléviseur, ajoutez la déclaration de fonctionnalité suivante au fichier manifeste de votre application :

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

Si vous autorisez votre application à s'exécuter sans appareil photo, ajoutez du code à votre application pour détecter si la fonctionnalité d'appareil photo est disponible et ajuster 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 qui ne sont pas équipés 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 économie d'énergie

Certains téléviseurs 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. Par conséquent, arrêtez tout contenu en cours de lecture lorsque l'appareil est en mode Économie d'énergie.

Pour éviter la lecture en mode faible 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 active au premier plan. Pour en savoir plus sur le démarrage et l'arrêt d'une activité, consultez Cycle de vie d'une activité.