Gestire l'hardware della TV

L'hardware della TV è sostanzialmente diverso da 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 per TV, gli utenti devono utilizzare un telecomando o un game pad. Quando crei un'app per la TV, devi considerare attentamente le limitazioni e i requisiti hardware dell'utilizzo dell'hardware TV.

Questa guida mostra come verificare se l'app è in esecuzione su una TV e come gestire le funzionalità hardware non supportate. Per scoprire i vari metodi di immissione, vedi Gestire i controller TV.

Cerca un dispositivo TV

Se stai creando un'app che funziona sia su dispositivi TV che su altri dispositivi, potresti dover controllare su quale tipo di dispositivo viene eseguita 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à sul telefono.

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à televisione. Il codice di esempio seguente mostra come verificare se la tua app è in esecuzione su un dispositivo TV:

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

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 delle funzionalità della tua app, potresti essere in grado di aggirare alcune funzionalità hardware che non sono disponibili. Questa sezione illustra quali funzionalità hardware non sono generalmente disponibili per la TV, come rilevare le funzionalità hardware mancanti e quali alternative vengono suggerite per queste funzionalità.

Funzionalità hardware della TV non supportate

Le TV hanno uno scopo diverso dagli altri dispositivi, pertanto non dispongono di funzionalità hardware che spesso altri dispositivi con piattaforma Android hanno. Per questo motivo, il sistema Android non supporta le seguenti funzionalità per i dispositivi TV:

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

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

Dichiarare 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 siano 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 individuare eventuali dichiarazioni dei requisiti hardware che potrebbero impedirne l'installazione su un dispositivo TV.

Se la tua app utilizza funzionalità hardware come touchscreen o fotocamera che non sono disponibili sulla TV, ma può funzionare senza l'uso di queste funzionalità, modifica il file manifest dell'app per indicare che queste funzionalità non sono necessarie. Il seguente snippet di codice manifest mostra come dichiarare che la tua app non richiede funzionalità hardware che non sono disponibili sui dispositivi TV, ma le utilizza 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à hanno funzionalità secondarie, come android.hardware.camera.front, come descritto nella sezione Riferimento alle funzionalità. Assicurati di contrassegnare come required="false" le eventuali funzionalità secondarie utilizzate anche nell'app.

Per tutte le app destinate all'utilizzo su dispositivi TV è necessario dichiarare che la funzionalità touchscreen non è richiesta, come descritto nella Guida introduttiva all'utilizzo delle app TV. Se normalmente la tua app utilizza una o più funzionalità non supportate dai dispositivi TV, modifica l'impostazione dell'attributo android:required in false per queste funzionalità nel file manifest.

Attenzione: la dichiarazione di una funzionalità hardware come richiesta impostando il relativo valore su true impedisce che l'app venga installata sui dispositivi TV o che venga visualizzata nell'Avvio app della schermata Home di Android TV.

Fai attenzione alle autorizzazioni che implicano funzionalità hardware.

Alcune dichiarazioni del file manifest di uses-permission presuppongono funzionalità hardware. Questo comportamento indica 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 delle funzionalità hardware:

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 nel file manifest una dichiarazione uses-feature per la funzionalità hardware implicita, che indica che non è necessaria. 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 la tua 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 quindi modificarne il comportamento. La prossima sezione illustra come verificare le funzionalità hardware e suggerisce alcuni approcci per modificare il comportamento della tua app.

Per maggiori informazioni su come filtrare e dichiarare le funzionalità nel manifest, consulta la guida uses-feature.

Verificare la presenza di funzionalità hardware

Il framework Android può indicare 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 prende un singolo argomento stringa che specifica la caratteristica che vuoi controllare.

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

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

// 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 touchscreen per i dispositivi TV. Inoltre, l'utilizzo 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 e il testo dell'interfaccia utente non richiedano o implichino l'uso di un touchscreen.

Per i dispositivi TV, progetta la tua app in modo che supporti la navigazione utilizzando un d-pad sul telecomando della TV. Per ulteriori informazioni su come supportare correttamente la navigazione utilizzando i controlli adatti alla TV, consulta la sezione Navigazione sulla TV.

Fotocamera

In genere, la TV non dispone di una fotocamera, ma sulla TV è possibile fornire un'app relativa alla fotografia. Ad esempio, se hai un'app che scatta, visualizza e modifica foto, puoi disattivare la relativa funzionalità per scattare foto per le TV e consentire agli utenti di visualizzare e persino modificare le foto. Se decidi di consentire il funzionamento dell'app relativa alla fotocamera sulla TV, aggiungi la seguente dichiarazione delle funzionalità nel file manifest dell'app:

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

Se consenti l'esecuzione dell'app senza fotocamera, aggiungi all'app codice che rilevi se la funzionalità della fotocamera è disponibile e apporta modifiche al funzionamento dell'app. Il seguente esempio di codice mostra come rilevare la presenza di una videocamera:

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

// 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 del sistema di posizionamento globale (GPS). Se la tua app utilizza informazioni sulla posizione, puoi comunque consentire agli utenti di cercare una località o utilizzare un fornitore di geolocalizzazione statico, ad esempio un codice postale configurato durante la configurazione del dispositivo TV.

// 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
        }

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

override fun onStop() {
    // App-specific method to stop playback.
    stopPlayback()
    super.onStop()
}

@Override
public void onStop() {
  // App-specific method to stop playback.
  stopPlayback();
  super.onStop();
}

Quando l'utente riattacca la corrente, se la tua app è l'app in primo piano attiva, viene chiamato onStart(). Per saperne di più su come avviare e interrompere un'attività, consulta Il ciclo di vita dell'attività.