Gérer le matériel TV

Le matériel TV est très différent des autres appareils Android. Les téléviseurs n'intègrent pas certaines des fonctionnalités matérielles d'autres appareils Android, telles que les écrans tactiles, les appareils photo et les récepteurs GPS. Les téléviseurs dépendent également complètement de périphériques matériels secondaires : pour que les utilisateurs puissent interagir avec les applications du téléviseur, ils doivent utiliser une télécommande ou une manette de jeu. Lorsque vous créez une application pour la télévision, vous devez bien prendre en compte les limites et exigences matérielles liées à l'utilisation de ce matériel.

Ce guide explique comment vérifier si votre application s'exécute sur un téléviseur et comment gérer les fonctionnalités matérielles non compatibles. Pour en savoir plus sur les différentes méthodes de saisie, consultez l'article Gérer les télécommandes de téléviseur.

Rechercher un téléviseur

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 elle s'exécute et ajuster son fonctionnement. Par exemple, si vous disposez d'une application qui peut être démarrée via un Intent, vérifiez les propriétés de l'appareil pour déterminer si une activité sur la télévision ou une activité téléphonique doit être lancée.

La méthode recommandée pour déterminer si votre application fonctionne sur un téléviseur consiste à utiliser la méthode PackageManager.hasSystemFeature() pour vérifier si l'appareil fonctionne en mode téléviseur. 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 décrit les fonctionnalités matérielles qui ne sont généralement pas disponibles pour les téléviseurs, comment détecter les fonctionnalités matérielles manquantes et les alternatives suggérées.

Fonctionnalités matérielles TV non compatibles

Les téléviseurs n'ont pas la même utilité que les autres appareils. Ils ne possèdent donc pas souvent les fonctionnalités matérielles des autres appareils Android. Par conséquent, 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 de téléviseur sont équipées d'un micro, qui est différent de la fonctionnalité matérielle du micro décrite ici. Le micro de la manette 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.

Déclarer la configuration matérielle requise pour les téléviseurs

Les applications Android peuvent déclarer des exigences de fonctionnalités matérielles dans le fichier manifeste de l'application afin de 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 son fichier manifeste pour identifier toute déclaration d'exigence matérielle pouvant 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 le 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 indisponibles sur les téléviseurs, mais qu'elle les utilise sur des 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 possèdent des sous-fonctionnalités, telles que 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 téléviseurs doivent déclarer que la fonctionnalité d'écran tactile n'est pas requise, comme décrit dans la section Premiers pas avec les applications pour téléviseur. Si votre application utilise normalement une ou plusieurs fonctionnalités non compatibles avec les téléviseurs, définissez le paramètre de l'attribut android:required sur false pour ces fonctionnalités dans votre fichier manifeste.

Attention:Le fait de déclarer une fonctionnalité matérielle comme requise en définissant sa valeur sur true empêche votre application d'être installée sur des appareils TV ou d'apparaître dans le lanceur de l'écran d'accueil d'Android TV.

Soyez conscient 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 le fait de demander des autorisations dans le fichier manifeste de votre application peut l'empêcher d'être installée et utilisée sur des téléviseurs. Les autorisations suivantes fréquemment 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 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 impliquant une exigence de fonctionnalité matérielle, consultez le guide uses-feature. Si votre application demande l'une des fonctionnalités précédemment répertoriées, incluez une déclaration uses-feature 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 version ultérieure et 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 de carte réseau ni de 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 différentes 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 guide uses-feature.

Rechercher 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 rechercher des fonctionnalités spécifiques au moment de l'exécution. Cette méthode utilise un seul argument de chaîne qui spécifie la fonctionnalité à 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

Comme la plupart des téléviseurs n'ont pas d'écran tactile, Android n'est pas compatible avec l'interaction avec l'écran tactile pour les téléviseurs. De plus, l'utilisation d'un écran tactile n'est pas cohérente avec un environnement de visionnage où l'utilisateur est assis à 3 mètres de l'écran. Assurez-vous que les éléments d'interface utilisateur et le texte ne nécessitent pas l'utilisation d'un écran tactile.

Pour les téléviseurs, concevez votre application pour qu'elle prenne en charge la navigation à l'aide du pavé directionnel de la télécommande d'un téléviseur. Pour savoir comment prendre en charge correctement la navigation à l'aide de commandes compatibles avec la télévision, consultez Navigation TV.

Appareil photo

Bien qu'un téléviseur ne soit généralement pas équipé d'un appareil photo, vous pouvez quand même proposer une application de photographie sur un téléviseur. Par exemple, si votre application prend, affiche et modifie des photos, vous pouvez désactiver cette fonctionnalité pour les téléviseurs tout en permettant aux utilisateurs d'afficher et même de modifier des photos. Si vous décidez d'autoriser votre application liée à l'appareil photo à fonctionner 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 permettez à votre application de s'exécuter sans caméra, ajoutez-lui un code qui détecte si la fonctionnalité de caméra est disponible et ajuste le fonctionnement de votre application. L'exemple de code suivant montre comment détecter la présence d'une caméra:

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 en 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 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 la lecture en pause en mode économie d'énergie

Certains téléviseurs sont compatibles avec un mode économie d'énergie lorsque l'utilisateur l'éteint. Au lieu de s'éteindre, l'appareil désactive l'affichage et maintient Android TV 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 le 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 remet le courant, 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 de l'activité.