L'hardware della TV è sostanzialmente diverso dagli altri dispositivi Android. Le TV non includono alcune funzionalità hardware presenti su altri dispositivi Android, come touchscreen, fotocamere e ricevitori GPS. Inoltre, le TV dipendono completamente da dispositivi hardware secondari: per consentire agli utenti di interagire con le app TV, è necessario utilizzare un telecomando o un gamepad. Per informazioni sui vari metodi di immissione, visita la pagina Gestire i controller della TV.
Quando crei un'app per la TV, considera con attenzione le limitazioni e i requisiti hardware per il funzionamento sull'hardware TV. Controlla se la tua app è in esecuzione su una TV e gestisci funzionalità hardware non supportate.
Verifica la presenza di 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 è in esecuzione l'app e regolare il funzionamento dell'app. Ad esempio, se hai un'app che può essere avviata tramite Intent,
controlla le proprietà del dispositivo per stabilire se avviare un'attività orientata alla TV
o un'attività telefonica.
Il metodo consigliato per determinare se la tua app è in esecuzione su un dispositivo TV è usare 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:
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 essere in grado di aggirare alcune funzionalità hardware non disponibili. Questa sezione illustra quali funzionalità hardware in genere non sono disponibili per la TV, come rilevare funzionalità hardware mancanti e quali alternative vengono suggerite per queste funzionalità.
Funzionalità hardware TV non supportate
Le TV hanno uno scopo diverso rispetto ad altri dispositivi, quindi non dispongono delle funzionalità hardware tipiche di altri dispositivi Android. Per questo motivo, il sistema Android non supporta le seguenti funzionalità per i dispositivi 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, che non è la stessa funzionalità hardware del microfono descritta qui. Il microfono del controller è completamente supportato.
Consulta la pagina Informazioni di riferimento sulle funzionalità per un elenco completo di caratteristiche, 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 le forniscono. Se stai estendendo un'app esistente per l'uso sulla TV, esamina attentamente il file manifest dell'app per verificare la presenza di eventuali 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 necessarie. Il seguente snippet di codice 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 funzionalità secondarie, come android.hardware.camera.front,
come descritto nella
Guida di riferimento alle funzionalità. Assicurati di contrassegnare tutte le funzionalità secondarie utilizzate anche nella tua app come required="false".
Per tutte le app destinate all'uso sui dispositivi TV è necessario dichiarare che la funzionalità touchscreen non è necessaria,
come descritto nella sezione Guida introduttiva alle
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 quelle funzionalità nel file manifest.
Attenzione:se dichiari una funzionalità hardware come richiesto impostando il relativo valore su true, l'app non potrà essere installata sui dispositivi TV o non verrà visualizzata nell'Avvio app della schermata Home di Android TV.
Presta attenzione alle autorizzazioni che implicano funzionalità hardware
Alcune dichiarazioni del file manifest di 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 richieste comunemente creano un requisito di funzionalità hardware implicita:
| Autorizzazione | Funzionalità hardware implicita |
|---|---|
RECORD_AUDIO |
android.hardware.microphone |
CAMERA |
android.hardware.camera e android.hardware.camera.autofocus |
ACCESS_COARSE_LOCATION |
|
ACCESS_FINE_LOCATION |
|
ACCESS_WIFI_STATECHANGE_WIFI_STATE
|
Alcuni dispositivi TV dispongono solo di una connessione Ethernet. |
Per un elenco completo delle richieste di autorizzazione che implicano un requisito delle funzionalità hardware, consulta la guida di 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 indichi 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 l'app
su un dispositivo TV, anche se il dispositivo TV non ha una scheda di rete o un ricevitore
GPS.
Dopo aver reso le funzionalità hardware facoltative per la tua app, devi verificare la disponibilità di queste funzionalità in fase di runtime, quindi modificare il comportamento dell'app. La prossima sezione illustra come verificare le funzionalità hardware e suggerisce alcuni approcci per modificare il comportamento dell'applicazione.
Per maggiori informazioni su come filtrare e dichiarare le funzionalità nel file manifest, consulta la guida di uses-feature.
Verificare 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 prende un singolo argomento stringa che specifica la caratteristica che vuoi controllare.
L'esempio di codice seguente 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
Poiché la maggior parte delle TV non dispone di touchscreen, Android non supporta l'interazione tramite 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 dell'interfaccia utente e il testo non richiedano o sottintendano l'uso di un touchscreen.
Per i dispositivi TV, progetta la tua app in modo da supportare la navigazione utilizzando un d-pad (d-pad) sul telecomando della TV. Per maggiori informazioni su come supportare correttamente la navigazione usando controlli che supportano la TV, vedi Navigazione TV.
Fotocamera
Anche se una TV in genere non dispone di una fotocamera, puoi comunque fornire un'app per la fotografia su una TV. Ad esempio, se hai un'app che acquisisce, visualizza e modifica le foto, puoi disattivare la relativa funzionalità di scatto per la TV e consentire comunque agli utenti di visualizzare e persino modificare le foto. Se decidi di consentire il funzionamento dell'app relativa alla videocamera su una 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 videocamera, aggiungi all'app codice che rilevi 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:
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 integrati. Se la tua app utilizza informazioni sulla posizione, puoi comunque consentire agli utenti di cercare una posizione o utilizzare un fornitore di posizione statico, come 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: 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 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. L'uscita audio è ancora attiva in questa modalità, quindi interrompi i contenuti 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 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 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à, consulta
Il ciclo di vita dell'attività.