Guida introduttiva alle app per TV

Le app TV utilizzano la stessa struttura delle app per smartphone e tablet. Questa somiglianza significa che puoi modificare le tue app esistenti in modo che vengano eseguite anche sui dispositivi TV o creare nuove app in base a ciò che già sai sulla creazione di app per Android.

Importante: la tua app deve soddisfare requisiti specifici per essere considerata un'app per Android TV su Google Play. Per maggiori informazioni, consulta i requisiti elencati in Qualità delle app TV.

Questa guida descrive come preparare il tuo ambiente di sviluppo per la creazione di app TV e le modifiche minime necessarie per consentire l'esecuzione di un'app sui dispositivi TV.

Per informazioni sulla progettazione di app per la TV, consulta la pagina Progettazione per la TV. Vedi anche le app di esempio nel repository GitHub di Android TV.

Determinare il supporto del formato multimediale

Consulta la seguente documentazione per informazioni su codec, protocolli e formati supportati da Android TV:

Configura un progetto TV

Questa sezione illustra come configurare un progetto TV, sia che tu stia modificando un'app per Android esistente per eseguirla sui dispositivi TV o creando una nuova app per TV. Se hai già un'app per Android, l'aggiunta del supporto di Android TV ti consente di progettare un'interfaccia utente per la TV riutilizzando l'architettura dell'app esistente.

Dichiarare un'attività TV

Un'applicazione destinata a essere eseguita sui dispositivi TV deve dichiarare un'attività di avvio applicazioni per la TV nel file manifest. A questo scopo, utilizza un filtro per intent CATEGORY_LEANBACK_LAUNCHER. Questo filtro identifica la tua app come attiva per la TV e consente a Google Play di identificarla come app TV. Quando un utente seleziona la tua app nella schermata Home della TV, questo intent identifica l'attività da avviare.

Il seguente snippet di codice mostra come includere questo filtro per intent nel tuo file manifest:

<application
  android:banner="@drawable/banner" >
  ...
  <activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
  </activity>

  <activity
    android:name="com.example.android.TvActivity"
    android:label="@string/app_name"
    android:theme="@style/Theme.Leanback">

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>

  </activity>
</application>

La seconda voce del file manifest delle attività in questo esempio specifica che è l'attività da avviare su un dispositivo TV.

Attenzione:se non includi il filtro per intent CATEGORY_LEANBACK_LAUNCHER nella tua app, non sarà visibile agli utenti che utilizzano Google Play sui dispositivi TV. Inoltre, se la tua app non ha questo filtro quando utilizzi gli strumenti per sviluppatori per caricarla su un dispositivo TV, l'app non viene visualizzata nell'interfaccia utente della TV.

L'interfaccia utente dell'app TV o la parte TV dell'app esistente deve fornire un'interfaccia semplice per facilitare la navigazione utilizzando un telecomando da 3 metri di distanza. Se stai modificando un'app esistente da usare sulla TV, non utilizzare per la TV lo stesso layout delle attività che utilizzi per smartphone e tablet. Per le linee guida sulla progettazione di un'app per la TV, consulta Progettazione per la TV. Per maggiori informazioni sui requisiti minimi di implementazione per i layout dell'interfaccia sulla TV, consulta Creare layout TV.

Dichiara il supporto dei dispositivi TV

Dichiara che la tua app è destinata ad Android TV dichiarando la funzionalità android.software.leanback.

Se l'app viene eseguita sia su dispositivi mobili che su TV, imposta il valore dell'attributo required su false. Se imposti il valore dell'attributo required su true, Google Play renderà disponibile la tua app solo sul sistema operativo Android TV. 

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

Dichiarazione touchscreen non richiesto

Le applicazioni per l'esecuzione su dispositivi TV non si basano sui touchscreen per l'input. Per essere chiari, il file manifest dell'app TV deve dichiarare che la funzionalità android.hardware.touchscreen non è necessaria. Questa impostazione identifica la tua app come in grado di funzionare su un dispositivo TV ed è obbligatoria affinché la tua app venga considerata un'app TV in Google Play. Il seguente esempio di codice mostra come includere questa dichiarazione del file manifest: 

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

Attenzione: nel file manifest dell'app devi dichiarare che non è necessario un touchscreen, come mostrato in questo esempio di codice. In caso contrario, l'app non viene visualizzata in Google Play sui dispositivi TV.

Fornisci un'icona e un banner nella schermata Home

Le app per Android TV devono fornire sia un'icona della schermata Home sia un'immagine del banner per ogni localizzazione. A seconda del dispositivo Android TV, l'icona o il banner viene utilizzato come punto di avvio dell'app visualizzato nella schermata Home nelle righe di app e giochi.

Per aggiungerli alla tua app, descrivi l'icona e il banner nel file manifest come segue: 

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

Icona della schermata Home

Le app Android TV, come tutte le app per Android, devono includere un'icona nella schermata Home. Per le best practice su come definire un punto di lancio efficace per la tua app e i requisiti dettagliati degli asset, consulta le linee guida per i banner e l'icona dell'app per Android TV.

Utilizza l'attributo android:banner con il tag <application> per fornire un banner predefinito per tutte le attività dell'applicazione oppure con il tag <activity> per fornire un banner per un'attività specifica.

Per il banner, utilizza una risorsa xhdpi di dimensioni pari a 320 x 180 pixel. Il testo deve essere incluso nell'immagine. Se la tua app è disponibile in più lingue, devi fornire versioni separate del banner con testo per ogni lingua supportata.

Modificare il colore di Avvio app

Attenzione:in Android 12 e versioni successive, le animazioni personalizzate della schermata iniziale create utilizzando l'API della piattaforma SplashScreen non sono supportate per le app Android TV.

All'avvio di un'app TV, il sistema mostra un'animazione simile a un cerchio pieno che si espande. Per personalizzare il colore di questa animazione, imposta l'attributo android:colorPrimary dell'app o dell'attività TV su un colore specifico. Inoltre, imposta due attributi di sovrapposizione delle transizioni su true come mostrato nello snippet seguente di un file XML di una risorsa del tema:

<resources>
    <style ... >
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>

Per ulteriori informazioni sull'utilizzo di temi e stili, consulta Stili e temi.

Crea un'app per il sistema operativo Android TV

La maggior parte delle librerie AndroidX può essere utilizzata con Android TV. Utilizza i componenti dell'architettura come ViewModel per gestire i dati dell'interfaccia utente sensibili al ciclo di vita e Room per integrarli con database SQLite locali come faresti per i dispositivi mobili.

La maggior parte delle librerie AndroidX supporta Android TV. Le app TV possono utilizzare gli stessi componenti dell'architettura delle app mobile. Puoi anche condividere i componenti tra fattori di forma, così devi solo specializzare la logica di presentazione della tua app TV.

Scrivi per la TV

Usa Jetpack Compose per creare l'UI del tuo sistema operativo TV. Compose è la moderna soluzione di Android per lo sviluppo della UI. Oltre alle librerie Compose principali, le librerie Compose per TV forniscono componenti dedicati progettati appositamente per lo schermo di casa:

Scopri come creare un'app TV con Compose per TV in Utilizzare Jetpack Compose su Android TV.

Toolkit UI Leanback (sconsigliato)

Il toolkit per la UI di Leanback fornisce da sempre API e widget dell'interfaccia utente esclusivamente per i dispositivi TV che utilizzano viste e frammenti Android:

Scopri come creare un'app TV con il toolkit Leanback UI in Utilizzo del toolkit Leanback UI.

Esegui app TV

L'esecuzione dell'app è una parte importante del processo di sviluppo. Puoi eseguire l'app su dispositivi TV configurati per supportare il debug USB o utilizzare i dispositivi TV virtuali.

Esegui su un dispositivo fisico

Configura il dispositivo TV come segue:

  1. Usa un cavo USB per collegare il dispositivo TV al computer di sviluppo. Se necessario, consulta la documentazione fornita dal produttore del dispositivo.
  2. Sul dispositivo TV, vai a Impostazioni.
  3. Nella riga Dispositivo, seleziona Informazioni.
  4. Scorri fino a Crea e seleziona Crea diverse volte fino a quando non visualizzi il messaggio "Ora sei uno sviluppatore".
  5. Torna a Impostazioni. Nella riga Preferenze, seleziona Opzioni sviluppatore.
  6. Seleziona Debug > Debug USB e poi On.
  7. Torna alla schermata Home della TV.

Per testare l'applicazione sul dispositivo TV:

  1. In Android Studio, seleziona il progetto e fai clic su Esegui nella barra degli strumenti.
  2. Nella finestra Seleziona destinazione deployment, seleziona il dispositivo TV e fai clic su OK.

Esegui su un dispositivo virtuale

Il gestore AVD nell'SDK per Android fornisce definizioni dei dispositivi che ti consentono di creare dispositivi TV virtuali per l'esecuzione e il test delle tue applicazioni.

Per creare un dispositivo TV virtuale:

  1. Avvia Gestione AVD. Per maggiori informazioni, consulta Creare e gestire dispositivi virtuali.
  2. Nella finestra di dialogo Gestione AVD, fai clic sulla scheda Definizioni dispositivo.
  3. Seleziona una delle definizioni di dispositivo Android TV e fai clic su Crea durata di visualizzazione media.
  4. Seleziona le opzioni dell'emulatore e fai clic su OK per creare la durata di visualizzazione media.

    Nota: per prestazioni ottimali dell'emulatore TV, utilizza l'emulatore x86 e attiva l'opzione Usa GPU host. Utilizza anche l'accelerazione dei dispositivi virtuali, se disponibile. Per maggiori informazioni sull'accelerazione hardware dell'emulatore, consulta Configurare l'accelerazione hardware per Android Emulator.

Per testare l'applicazione sul dispositivo TV virtuale:

  1. In Android Studio, seleziona il progetto e fai clic su Esegui nella barra degli strumenti.
  2. Nella finestra Seleziona destinazione deployment, seleziona il tuo dispositivo TV virtuale e fai clic su Ok.

Per maggiori informazioni sull'utilizzo degli emulatori, vedi Eseguire app sull'emulatore Android. Per ulteriori informazioni sul deployment di app da Android Studio ai dispositivi virtuali, vedi Eseguire il debug delle app.

Attiva l'esecuzione dell'app TV come app istantanea

Le esperienze istantanee semplificano agli utenti provare la tua app TV e possono contribuire ad aumentarne l'adozione.

Per configurare l'app TV in modo che venga eseguita come app istantanea su un emulatore o un dispositivo Android TV, segui innanzitutto le istruzioni per creare un app bundle ad attivazione istantanea.

Dopodiché, nel intent-filter per il valore MainActivity dell'app TV, assicurati che LAUNCHER e LEANBACK_LAUNCHER siano dichiarati in AndroidManifest.xml: 

<activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
  </activity>

L'app TV è ora configurata per essere eseguita come app istantanea.

Preparare l'app TV per la pubblicazione

Consulta l'elenco di controllo delle app TV per i passaggi successivi in modo da preparare la tua app TV per la pubblicazione e la distribuzione.