Gestire l'hardware della TV

L'hardware della TV è sostanzialmente diverso da quello di altri dispositivi Android. Le TV non includono alcune funzionalità hardware presenti su altri dispositivi Android, come touchscreen, videocamere 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 scoprire di più sui vari metodi di inserimento, vedi Gestire i controller TV.)

Quando crei un'app per la TV, considera attentamente le limitazioni e i requisiti hardware per il funzionamento sull'hardware TV. Controlla se la tua app viene eseguita su una TV e gestisci le funzionalità hardware non supportate.

Cercare un dispositivo TV

Se stai creando un'app che funziona sia su dispositivi TV sia su altri dispositivi, potresti dover controllare su quale tipo di dispositivo è 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 viene eseguita su un dispositivo TV è utilizzare il metodo PackageManager.hasSystemFeature() per verificare se il dispositivo è in modalità TV. Il seguente codice di esempio 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 della funzionalità della tua app, potresti essere in grado di aggirare l'indisponibilità di determinate funzionalità hardware. Questa sezione descrive le funzionalità hardware in genere non 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, quindi non dispongono di funzionalità hardware che spesso sono presenti in altri dispositivi basati su Android. Per questo motivo, il sistema Android non supporta le seguenti funzionalità per un dispositivo TV:

Nota:alcuni telecomandi della TV hanno un microfono, che non è lo stesso 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.

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 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 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 l'utilizzo di queste funzionalità, modifica il file manifest dell'app per indicare che queste funzionalità non sono richieste. Lo snippet di codice manifest seguente mostra come dichiarare che l'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 delle sottofunzionalità, come android.hardware.camera.front, come descritto nel riferimento alle funzionalità. Assicurati di contrassegnare come required="false" anche le funzionalità secondarie utilizzate nella tua app.

Tutte le app destinate all'uso su dispositivi TV devono dichiarare che la funzionalità touchscreen non è richiesta, 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 relativo valore su true, l'app non potrà essere installata su dispositivi TV né visualizzata nel launcher della schermata Home di Android TV.

Tieni presente le 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ò escludere l'app dall'installazione e dall'utilizzo sui dispositivi TV. Le seguenti autorizzazioni richieste di frequente creano un requisito implicito per le 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 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 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 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 dell'app.

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

Controllare le 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 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:

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

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

Per saperne di più su come supportare correttamente la navigazione utilizzando controlli compatibili con la TV, consulta la pagina Navigazione TV.

Dichiarare il supporto del tocco

Alcuni dispositivi TV supportano i telecomandi con puntatore e i display touchscreen. La tua app può supportare 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 nel tuo AndroidManifest.xml:

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

Nota: sui dispositivi che supportano un telecomando con puntatore (come un air mouse o un trackpad), l'attivazione di questa consente la modalità cursore e tocco 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 videocamera, puoi comunque fornire un'app correlata 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 attivare l'app correlata alla videocamera su una TV, aggiungi la seguente dichiarazione di funzionalità al manifest dell'app:

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

Se abiliti l'esecuzione dell'app senza una videocamera, aggiungi codice all'app che rileva se la funzionalità della videocamera è 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 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 fornitore di posizione statica, 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 durante la modalità a basso consumo

Alcuni dispositivi TV supportano una modalità a basso consumo energetico quando l'utente spegne il dispositivo. Anziché spegnersi, il dispositivo disattiva il display e mantiene Android TV in esecuzione in background. L'uscita audio è comunque attiva in questa modalità, quindi interrompi la riproduzione di qualsiasi contenuto quando il dispositivo è in modalità di risparmio energetico.

Per evitare la riproduzione durante la modalità di risparmio energetico, esegui l'override onStop() e interrompi la riproduzione dei contenuti in corso:

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 riattiva l'alimentazione, viene chiamato onStart() se la tua app è l'app attiva in primo piano. Per ulteriori informazioni sull'avvio e l'interruzione di un'attività, consulta Il ciclo di vita dell'attività.