Gérer le matériel TV

Le matériel TV est très différent des autres appareils Android. Les téléviseurs n'incluent pas certaines fonctionnalités matérielles présentes sur d'autres appareils Android, comme les écrans tactiles, les caméras et les récepteurs GPS. Les téléviseurs dépendent également entièrement des périphériques secondaires : pour interagir avec les applications TV, les utilisateurs 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 téléviseur, tenez compte des limites et des exigences matérielles liées à l'exécution sur un téléviseur. 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 téléviseurs 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 avez une application qui peut être démarré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é de téléphone.

La méthode recommandée pour déterminer si votre application s'exécute sur un téléviseur consiste à utiliser la méthode PackageManager.hasSystemFeature() pour vérifier si l'appareil est en mode télévision. L'exemple de code suivant vous 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")
}

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 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 TV non compatibles

Les téléviseurs ont une fonction différente de celle des autres appareils. Ils ne disposent donc pas des fonctionnalités matérielles que les autres appareils Android ont souvent. Pour cette raison, le système Android ne prend pas en charge les fonctionnalités suivantes pour un téléviseur :

Matériel	Descripteur de caractéristiques 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 le micro matériel décrit 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 descriptions.

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

Les applications Android peuvent déclarer des exigences concernant les 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 proposent 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 l'empêcher d'être installée sur un téléviseur.

Si votre application utilise des fonctionnalités matérielles comme un écran tactile ou une caméra qui ne sont pas disponibles sur TV, mais qu'elle peut fonctionner sans les utiliser, 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 n'a pas besoin de fonctionnalités matérielles qui ne sont pas disponibles sur les appareils TV, mais qu'elle utilise ces fonctionnalités sur les appareils autres que les téléviseurs :

<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 référence des 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 prises en charge par les appareils TV, définissez l'attribut android:required sur false pour ces fonctionnalités dans votre fichier manifeste.

Attention : Si vous déclarez qu'une fonctionnalité matérielle est requise en définissant sa valeur sur true, votre application ne pourra pas être installée sur les téléviseurs ni s'afficher dans le lanceur d'écran d'accueil Android TV.

Être attentif aux autorisations qui impliquent des fonctionnalités matérielles

Certaines déclarations de fichier manifeste uses-permission impliquent des fonctionnalités matérielles. Cela signifie que le fait de demander certaines autorisations dans le fichier manifeste de votre application peut empêcher son installation et son utilisation sur des appareils TV. Les autorisations couramment demandées suivantes créent une exigence implicite concernant une 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 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 impliquée, en 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 installer votre application sur un téléviseur, même si celui-ci ne dispose pas d'une carte réseau ni d'un récepteur GPS.

Une fois que vous avez 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 s'exécute. Utilisez la méthode hasSystemFeature(String) pour vérifier la présence de 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.")
}

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 sont pas équipés d'écrans tactiles ni de pointeurs, et s'appuient entièrement sur 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 correcte de la navigation à l'aide de commandes adaptées aux téléviseurs, consultez Navigation TV.

Déclarer la compatibilité avec le mode 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 par clic, par pointage et par défilement, comme sur un appareil mobile, pour offrir une meilleure expérience sur les appareils qui les prennent en charge.

Si votre application autorise le mode tactile, vous pouvez déclarer la compatibilité 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 de pointage (comme une souris gyroscopique ou un pavé tactile), l'activation de cette option permet d'utiliser le mode curseur et le mode tactile au lieu 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 avez une application qui prend, affiche et modifie des photos, vous pouvez désactiver sa fonctionnalité de prise de photos pour les téléviseurs tout en permettant aux utilisateurs de visualiser et même de modifier des photos. Si vous décidez d'activer votre application liée à la caméra 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 qui détecte si la fonctionnalité de l'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.")
}

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 sont pas équipés de récepteurs GPS (Global Positioning System). Si votre application utilise des informations de localisation, vous pouvez toujours autoriser les utilisateurs à rechercher un lieu ou à 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: Location = locationManager.getLastKnownLocation("static")

// 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)[0]
                    .apply {
                        Log.d(TAG, postalCode)
                    }
        } catch (e: IOException) {
            Log.e(TAG, "Geocoder error", e)
            null
        }

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 prennent en charge 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 fonctionnement en arrière-plan. La sortie audio étant toujours activée dans ce mode, arrêtez tout contenu en cours de lecture lorsque l'appareil est en mode économie d'énergie.

Pour éviter la lecture en mode économie d'énergie, 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 réactive l'alimentation, 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 Cycle de vie d'une activité.