Gestire l'hardware della TV

L'hardware TV è sostanzialmente diverso da quello di altri dispositivi Android. Le TV non includono alcune delle funzionalità hardware presenti su altri dispositivi Android, come touchscreen, fotocamere e ricevitori GPS. Inoltre, le TV dipendono completamente da dispositivi hardware secondari: per interagire con le app TV, gli utenti devono utilizzare un telecomando o un gamepad. (Per scoprire di più sui vari metodi di input, consulta Gestire i controller TV.)

Quando crei un'app per la TV, tieni attentamente in considerazione le limitazioni e i requisiti hardware per il funzionamento sull'hardware TV. Controlla se la tua app è in esecuzione su una TV e gestisci le funzionalità hardware non supportate.

Controllare se è presente un dispositivo TV

Se stai creando un'app che funziona sia su dispositivi TV sia su altri dispositivi, potresti dover controllare il tipo di dispositivo su cui è in esecuzione l'app e regolarne il funzionamento. Ad esempio, se hai un'app che può essere avviata tramite un Intent, controlla le proprietà del dispositivo per determinare se avviare un'attività orientata alla TV o un'attività per smartphone.

Il modo consigliato per determinare se la tua app è in esecuzione su un dispositivo TV è utilizzare il metodo PackageManager.hasSystemFeature per verificare se il dispositivo è in esecuzione in modalità TV. Il seguente esempio di codice mostra come verificare se la tua app è in esecuzione su un dispositivo 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")
}

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");
}

Gestire le funzionalità hardware non supportate

A seconda del design e della funzionalità della tua app, potresti essere in grado di aggirare l'indisponibilità di alcune funzionalità hardware. Questa sezione illustra le funzionalità hardware che in genere non sono disponibili per la TV, come rilevare le funzionalità hardware mancanti e quali alternative sono suggerite per queste funzionalità.

Funzionalità hardware TV non supportate

Le TV hanno uno scopo diverso rispetto ad altri dispositivi, pertanto non dispongono di funzionalità hardware che spesso sono presenti su altri dispositivi con Android. Per questo motivo, il sistema Android non supporta le seguenti funzionalità per un dispositivo TV:

Hardware Descrittore della funzionalità Android
Touchscreen android.hardware.touchscreen
Emulatore touchscreen android.hardware.faketouch
Telefonia android.hardware.telephony
Fotocamera android.hardware.camera
Near Field Communication (NFC) android.hardware.nfc
GPS android.hardware.location.gps
Microfono android.hardware.microphone
Sensori android.hardware.sensor
Schermo in orientamento verticale android.hardware.screen.portrait

Nota: alcuni controller TV hanno un microfono, che non è la stessa funzionalità hardware del microfono descritta qui. Il microfono del controller è completamente supportato.

Per un elenco completo delle funzionalità, delle sottofunzionalità e dei relativi descrittori, consulta la documentazione di riferimento sulle funzionalità.

Dichiarare i requisiti hardware per la TV

Le app Android possono dichiarare i requisiti delle funzionalità hardware nel file manifest dell'app per assicurarsi che non vengano installate su dispositivi che non forniscono queste funzionalità. Se stai estendendo un'app esistente per l'utilizzo sulla TV, esamina attentamente il file manifest dell'app per verificare la presenza di dichiarazioni di requisiti hardware che potrebbero impedirne l'installazione su un dispositivo TV.

Se la tua app utilizza funzionalità hardware come un touchscreen o una fotocamera che non sono disponibili sulla TV, ma può funzionare senza utilizzare queste funzionalità, modifica il file manifest dell'app per indicare che queste funzionalità non sono obbligatorie. Il seguente snippet di codice del file manifest mostra come dichiarare che la tua app non richiede funzionalità hardware non disponibili sui dispositivi TV, ma le utilizza su dispositivi 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"/>

Nota: alcune funzionalità hanno sottofunzionalità, come android.hardware.camera.front, come descritto nella documentazione di riferimento sulle funzionalità. Assicurati di contrassegnare anche le sottofunzionalità utilizzate nella tua app come required="false".

Tutte le app destinate all'uso su dispositivi TV devono dichiarare che la funzionalità touchscreen non è obbligatoria, come descritto in Iniziare a utilizzare le app TV. Se la tua app utilizza normalmente una o più delle funzionalità non supportate dai dispositivi TV, modifica l'impostazione dell'attributo android:required in false per queste funzionalità nel file manifest.

Attenzione: se dichiari che una funzionalità hardware è obbligatoria impostando il relativo valore su true l'app non potrà essere installata sui dispositivi TV o visualizzata nel launcher della schermata Home di Android TV.

Conoscere le autorizzazioni che implicano funzionalità hardware

Alcune uses-permission dichiarazioni del file manifest implicano funzionalità hardware. Questo comportamento significa che la richiesta di alcune autorizzazioni nel file manifest dell'app può impedire l'installazione e l'utilizzo dell'app sui dispositivi TV. Le seguenti autorizzazioni richieste di frequente creano un requisito implicito per le funzionalità hardware:

Autorizzazione Funzionalità hardware implicita
RECORD_AUDIO android.hardware.microphone
CAMERA android.hardware.camera e
android.hardware.camera.autofocus
ACCESS_COARSE_LOCATION

android.hardware.location

android.hardware.location.network (solo livello API target 20 o inferiore )
ACCESS_FINE_LOCATION

android.hardware.location

android.hardware.location.gps (solo livello API target 20 o inferiore )
ACCESS_WIFI_STATE
CHANGE_WIFI_STATE

android.hardware.wifi

Alcuni dispositivi TV hanno solo una connessione Ethernet.

Per un elenco completo delle richieste di autorizzazioni che implicano un requisito per le funzionalità hardware, consulta la uses-feature guida. Se la tua app richiede una delle funzionalità elencate in precedenza, includi una uses-feature dichiarazione nel file manifest per la funzionalità hardware implicita che indica che non è obbligatoria. android:required="false".

Nota: se la tua app ha come target Android 5.0 (livello API 21) o versioni successive e utilizza l'autorizzazione ACCESS_COARSE_LOCATION o ACCESS_FINE_LOCATION, gli utenti possono comunque installare l'app su un dispositivo TV, anche se il dispositivo TV non dispone di una scheda di rete o di un ricevitore GPS.

Dopo aver reso facoltative le funzionalità hardware per la tua app, devi verificarne la disponibilità in fase di runtime e poi modificare il comportamento dell'app. La sezione successiva illustra come verificare la presenza di funzionalità hardware e suggerisce alcuni approcci per modificare il comportamento dell'app.

Per ulteriori informazioni sul filtraggio e sulla dichiarazione delle funzionalità nel file manifest, consulta la uses-feature guida.

Verificare la presenza di funzionalità hardware

Il framework Android può indicarti se le funzionalità hardware non sono disponibili sul dispositivo su cui è in esecuzione la tua app. Utilizza il metodo hasSystemFeature(String) per verificare la presenza di funzionalità specifiche in fase di runtime. Questo metodo accetta un singolo argomento stringa che specifica la funzionalità che vuoi controllare.

Il seguente esempio di codice mostra come rilevare la disponibilità delle funzionalità hardware in fase di runtime:

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.");
}

Touchscreen

La maggior parte dei dispositivi TV non dispone di touchscreen o funzionalità di input tramite puntatore e si basa completamente sui telecomandi con D-pad per la navigazione. Le app TV devono sempre supportare un telecomando con D-pad.

Per ulteriori informazioni sul supporto corretto della navigazione utilizzando i controlli adatti alla TV, consulta Navigazione TV.

Dichiarare il supporto del tocco

Alcuni dispositivi TV supportano i telecomandi con puntatore e i display touchscreen. La tua app può supportare le interazioni di clic, passaggio del mouse e scorrimento, come su un dispositivo mobile, per offrire un'esperienza migliore sui dispositivi che le supportano.

Se la tua app consente la modalità touch, puoi dichiarare il supporto del tocco aggiungendo android.software.leanback.supports_touch impostato su true in AndroidManifest.xml: 

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

Nota: sui dispositivi che supportano un telecomando con puntatore (ad esempio un air mouse o un trackpad), l'attivazione di questa opzione abilita la modalità cursore e touch anziché basarsi sull'emulazione della compatibilità della piattaforma. Se ometti questi metadati, il valore predefinito è false.

Fotocamera

Anche se in genere una TV non ha una fotocamera, puoi comunque fornire un'app relativa alla fotografia su una TV. Ad esempio, se hai un'app che scatta, visualizza e modifica le foto, puoi disattivare la funzionalità di scatto di foto per le TV e consentire comunque agli utenti di visualizzare e persino modificare le foto. Se decidi di abilitare l'app relativa alla fotocamera per il funzionamento su una TV, aggiungi la seguente dichiarazione di funzionalità al file manifest dell'app: 

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

Se abiliti l'esecuzione dell'app senza una fotocamera, aggiungi codice all'app per rilevare se la funzionalità della fotocamera è disponibile e apportare modifiche al funzionamento della tua app. Il seguente esempio di codice mostra come rilevare la presenza di una fotocamera:

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

Le TV sono dispositivi fissi per interni e non dispongono di ricevitori GPS (Global Positioning System) integrati. Se la tua app utilizza le informazioni sulla posizione, puoi comunque consentire agli utenti di cercare una posizione o utilizzare un provider di posizione statico, ad esempio un codice postale configurato durante la configurazione del dispositivo 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
        }

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);
}

Mettere in pausa la riproduzione durante la modalità a basso consumo

Alcuni dispositivi TV supportano una modalità a basso consumo quando l'utente spegne il dispositivo. Anziché spegnersi, il dispositivo disattiva il display e mantiene Android TV in esecuzione in background. In questa modalità, l'output audio è ancora attivo, quindi interrompi la riproduzione di qualsiasi contenuto in corso quando il dispositivo è in modalità a basso consumo.

Per evitare la riproduzione durante la modalità a basso consumo, esegui l'override di onStop e interrompi la riproduzione di qualsiasi contenuto in corso:

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();
}

Quando l'utente riaccende il dispositivo, viene chiamato onStart se la tua app è l'app in primo piano attiva. Per ulteriori informazioni sull'avvio e l'arresto di un'attività, consulta Il ciclo di vita dell'attività.

Indietro
Creare ed eseguire un'app TV
Avanti
Gestire i controller TV