Gestire l'hardware della TV

L'hardware della 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. Le TV dipendono inoltre completamente da dispositivi hardware secondari: per interagire con le app TV, gli utenti devono utilizzare un telecomando o un gamepad. Per scoprire i vari metodi di input, consulta Gestisci i controller della TV.

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

Controlla se è presente un dispositivo TV

Se stai creando un'app che funziona sia su TV che su altri dispositivi, potresti dover controllare su quale tipo di dispositivo è in esecuzione l'app e regolare il funzionamento dell'app. 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 codice di esempio 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")
}
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");
}

Gestisci le funzionalità hardware non supportate

A seconda del design e della funzionalità della tua app, potresti essere in grado di aggirare la mancata disponibilità 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 della TV non supportate

Le TV hanno uno scopo diverso rispetto ad altri dispositivi, quindi non hanno le funzionalità hardware che spesso hanno altri dispositivi Android. Per questo motivo, il sistema Android non supporta le seguenti funzionalità per un dispositivo TV:

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

Nota: alcuni controller TV sono dotati di un microfono, che non è la stessa cosa della funzionalità hardware del microfono descritta qui. Il microfono del controller è completamente supportato.

Consulta il riferimento alle funzionalità per un elenco completo di funzionalità, sottofunzionalità e relativi descrittori.

Dichiara i requisiti hardware per la TV

Le app per Android possono dichiarare i requisiti delle funzionalità hardware nel file manifest dell'app per garantire 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 manifest dell'app per verificare la presenza di dichiarazioni dei 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 richieste. Il seguente snippet di codice del manifest mostra come dichiarare che la tua app non richiede funzionalità hardware non disponibili su dispositivi TV, ma utilizza queste funzionalità 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 funzionalità secondarie, come android.hardware.camera.front, come descritto nel riferimento delle funzionalità. Assicurati di contrassegnare come required="false" anche le funzionalità secondarie utilizzate nella tua app.

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

Attenzione: se dichiari una funzionalità hardware come obbligatoria impostando il suo valore su true, l'app non potrà essere installata sui dispositivi TV o visualizzata nell'Avvio app della schermata Home di Android TV.

Presta attenzione alle autorizzazioni che implicano funzionalità hardware

Alcune dichiarazioni del manifest uses-permission 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 comunemente richieste 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 precedente)
ACCESS_FINE_LOCATION	android.hardware.location android.hardware.location.gps (solo livello API target 20 o precedente)
ACCESS_WIFI_STATE CHANGE_WIFI_STATE	android.hardware.wifi Alcuni dispositivi TV hanno solo una connessione Ethernet.

Per un elenco completo delle richieste di autorizzazione che implicano un requisito di funzionalità hardware, consulta la guida uses-feature. Se la tua app richiede una delle funzionalità elencate in precedenza, includi una dichiarazione uses-feature nel 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 installarla su un dispositivo TV, anche se quest'ultimo non dispone di una scheda di rete o di un ricevitore GPS.

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

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

Verifica delle 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 di stringa che specifica la funzionalità che vuoi controllare.

Il seguente esempio di codice mostra come rilevare la disponibilità delle funzionalità hardware durante il 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.")
}
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.");
}

Touchscreen

La maggior parte dei dispositivi TV non dispone di touchscreen o funzionalità di input del puntatore e si affida completamente ai telecomandi con D-pad (croce direzionale) per la navigazione. Le app TV devono sempre supportare un telecomando D-pad.

Per saperne di più su come supportare correttamente la navigazione utilizzando controlli adatti alla TV, consulta Navigazione TV.

Dichiara 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 touch per l'intera app o per singole attività aggiungendo l'elemento android.software.leanback.supports_touch <property> impostato su true all'interno dell'elemento <application> o <activity> nel tuo AndroidManifest.xml:

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

Nota: sui dispositivi che supportano un telecomando di puntamento (come un mouse o un trackpad), l'attivazione di questa opzione attiva la modalità cursore e tocco anziché fare affidamento sull'emulazione di compatibilità della piattaforma. Una dichiarazione a livello di attività sostituisce la dichiarazione a livello di applicazione per l'attività in questione. Se questa proprietà viene omessa, il valore predefinito è false.

Fotocamera

Sebbene una TV in genere non disponga di una fotocamera, puoi comunque fornire un'app correlata alla fotografia su una TV. Ad esempio, se hai un'app che scatta, visualizza e modifica foto, puoi disattivare la funzionalità di scatto per le TV e consentire comunque agli utenti di visualizzare e persino modificare le foto. Se decidi di attivare la tua app correlata alla fotocamera per l'utilizzo su una TV, aggiungi la seguente dichiarazione della funzionalità al manifest dell'app:

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

Se attivi l'app in modo che funzioni senza fotocamera, aggiungi alla tua app un codice che rilevi se la funzionalità della fotocamera è disponibile e apporti modifiche al funzionamento dell'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.")
}
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

Le TV sono dispositivi fissi per interni e non dispongono di ricevitori GPS (Global Positioning System) integrati. Se la tua app utilizza i dati 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
        }
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);
}

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

Alcuni dispositivi TV supportano una modalità a basso consumo quando l'utente li spegne. Anziché spegnersi, il dispositivo disattiva il display e mantiene Android TV in esecuzione in background. L'uscita audio è ancora attiva in questa modalità, quindi interrompi la riproduzione di qualsiasi contenuto 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 i contenuti attualmente in riproduzione:

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 attiva in primo piano. Per ulteriori informazioni sull'avvio e sull'arresto di un'attività, consulta Il ciclo di vita dell'attività.