Gestire l'hardware della TV

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

Quando crei un'app per la TV, considera con attenzione le limitazioni e i requisiti hardware su hardware TV. Controlla se la tua app è in esecuzione su una TV e gestisci i dispositivi non supportati funzionalità hardware.

Verifica la presenza di un dispositivo TV

Se stai creando un'app che funziona sia su dispositivi TV che su altri dispositivi, potresti dover controlla il tipo di dispositivo su cui è in esecuzione la tua app e regolane il funzionamento. Per Ad esempio, se hai un'app che può essere avviata tramite un Intent, Controllare le proprietà del dispositivo per stabilire se iniziare una un'attività fisica o un'attività dello smartphone.

Il metodo consigliato per determinare se la tua app è in esecuzione su un dispositivo TV è usare il metodo PackageManager.hasSystemFeature() per controllare se il dispositivo è in modalità televisione. 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")
}

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 della progettazione e della funzionalità dell'app, potresti riuscire ad aggirare alcuni funzionalità hardware non disponibili. Questa sezione illustra le caratteristiche tipiche dell'hardware non disponibile per la TV, come rilevare funzionalità hardware mancanti e quali alternative vengono suggerite queste funzionalità.

Funzionalità hardware TV non supportate

Le TV hanno uno scopo diverso dagli altri dispositivi, quindi non dispongono di 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à 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 con orientamento verticale	android.hardware.screen.portrait

Nota:alcuni controller TV sono dotati di un microfono, non corrisponde alla funzionalità hardware del microfono descritta qui. Il microfono del controller è completamente supportati.

Consulta Riferimento alle funzionalità per un elenco completo di funzionalità, funzionalità secondarie e descrittori.

Dichiarare i requisiti hardware per la TV

Le app per Android possono dichiarare i requisiti relativi alle funzionalità hardware nel file manifest dell'app per garantire che non sono installati su dispositivi che non le forniscono. Se intendi estendere un modello esistente per l'uso sulla TV, esamina attentamente il file manifest dell'app per verificare la presenza di eventuali requisiti hardware dichiarazioni che potrebbero impedirne l'installazione su un dispositivo TV.

Se la tua app usa funzionalità hardware non disponibili sul touchscreen o una fotocamera TV, ma può funzionare senza utilizzare queste funzionalità, modificare il file manifest dell'app in indicano che queste funzionalità non sono obbligatorie. Il seguente snippet di codice manifest dimostra come dichiarare che la tua app non richiede funzionalità hardware non disponibili sui dispositivi TV, ma utilizza queste funzionalità su dispositivi diversi dalla 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à includono funzionalità secondarie, ad esempio android.hardware.camera.front, come descritto in Informazioni sulle funzionalità. Assicurati di contrassegnare tutte le funzionalità secondarie utilizzate anche nella tua app come required="false".

Tutte le app destinate all'uso sui dispositivi TV devono dichiarare che la funzionalità touchscreen non è necessaria. come descritto nella Guida introduttiva all'utilizzo di App TV. Se normalmente la tua app utilizza una o più funzionalità non supportate dai dispositivi TV, modifica Impostazione dell'attributo android:required su false per queste funzionalità nel file manifest.

Attenzione:dichiara una funzionalità hardware come richiesto impostandone pari a true impedisce l'installazione dell'app sulla TV dispositivi o che appaiono nell'Avvio app della schermata Home di Android TV.

Presta attenzione alle autorizzazioni che implicano funzionalità hardware

Alcune uses-permission le dichiarazioni del file manifest implicano le funzionalità hardware. Questo comportamento significa che la richiesta le autorizzazioni nel file manifest dell'app possono impedire l'installazione e l'utilizzo della tua app sulla TV dispositivi mobili. Le seguenti autorizzazioni richieste comunemente creano una funzionalità hardware implicita requisito:

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 (livello API target 20 o precedente) )
ACCESS_FINE_LOCATION	android.hardware.location android.hardware.location.gps (livello API target 20 o precedente) )
ACCESS_WIFI_STATE CHANGE_WIFI_STATE	android.hardware.wifi Alcuni dispositivi TV dispongono solo di una connessione Ethernet.

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

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

Dopo aver reso facoltative le funzionalità hardware per la tua app, devi controllare la disponibilità di queste funzionalità in fase di runtime, quindi modifica il comportamento dell'app. La sezione successiva illustra come verificare le funzionalità hardware e suggerisce alcuni approcci per cambiare comportamento dell'app.

Per ulteriori informazioni su come filtrare e dichiarare le caratteristiche nel file manifest, consulta uses-feature guida.

Verificare le funzionalità hardware

Il framework Android è in grado di indicare se le funzionalità hardware non sono disponibili sul dispositivo su cui la tua app è in esecuzione. Usa hasSystemFeature(String) per controllare funzionalità specifiche in fase di runtime. Questo metodo prende un singolo argomento stringa specifica la caratteristica che vuoi controllare.

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

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

Poiché la maggior parte delle TV non dispone di touchscreen, Android non supporta l'interazione con il touchscreen per Dispositivi TV. Inoltre, l'uso di un touchscreen non è coerente con un ambiente di visualizzazione in cui l'utente è seduto a 3 metri di distanza dal display. Assicurati che gli elementi dell'interfaccia utente e il testo non richiedono o implicano l'uso di un touchscreen.

Per i dispositivi TV, progetta la tua app in modo che supporti la navigazione usando un pad direzionale (D-pad) sul telecomando di una TV. Per ulteriori informazioni supportare correttamente la navigazione con controlli compatibili con la TV; consulta Navigazione TV.

Fotocamera

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

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

Se consenti l'esecuzione dell'app senza videocamera, aggiungi il codice all'app che rileva se la funzione della videocamera è disponibile e regola il funzionamento del dell'app. Il seguente esempio di codice mostra come rilevare la presenza di una videocamera:

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 all'interno e non dispongono di un sistema di posizionamento globale (GPS) integrato o ricevitori. Se la tua app utilizza informazioni sulla posizione, puoi comunque consentire agli utenti di cercare una posizione o utilizzare un fornitore di servizi di localizzazione statico come un codice postale configurato durante il dispositivo TV configurazione.

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

Mettere in pausa la riproduzione in modalità a basso consumo

Alcuni dispositivi TV supportano la modalità a basso consumo quando l'utente spegne il dispositivo. Anziché arrestarsi, il dispositivo disattiva il display e mantiene Android TV in esecuzione in background. L'uscita audio è ancora attiva in questa modalità, quindi interrompere i contenuti attualmente in riproduzione quando il dispositivo è in modalità a basso consumo.

Per evitare la riproduzione in modalità a basso consumo, sostituisci onStop() e interrompi i contenuti 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 riattacca la corrente, viene chiamato onStart() se la tua app è l'app attiva in primo piano. Per ulteriori informazioni su come avviare e interrompere un'attività, vedi Il ciclo di vita dell'attività.