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 poter essere considerata app per Android TV su Google Play. Per maggiori informazioni, consulta i requisiti elencati in Qualità delle app TV.

Questa guida descrive come preparare l'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, vedi Design per la TV. Controlla anche le app di esempio nel repository GitHub di Android TV.

Determinare il supporto dei formati multimediali

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

Configurare un progetto TV

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

Quando crei un'app eseguita sui dispositivi TV, i componenti principali da utilizzare sono due:

  • Attività per la TV: nel file manifest dell'applicazione, dichiara un'attività da eseguire sui dispositivi TV.
  • Librerie TV: se vuoi, includi una o più librerie Androidx disponibili per i dispositivi TV, elencate in un'altra sezione di questa guida. Queste librerie forniscono widget per la creazione delle interfacce utente.

Prerequisiti

Prima di iniziare a creare un'app per la TV, devi svolgere i seguenti passaggi:

  • Aggiorna gli strumenti dell'SDK alla versione 24.0.0 o successive.
    Gli strumenti SDK aggiornati ti consentono di creare e testare app per la TV.
  • Aggiorna l'SDK con Android 5.0 (API 21) o versioni successive.
    La versione aggiornata della piattaforma fornisce nuove API per le app TV.
  • Crea o aggiorna il progetto dell'app.
    Per accedere a nuove API per i dispositivi TV, crea un progetto o modificane uno esistente che abbia come target Android 5.0 (livello API 21) o versioni successive.

Dichiarare un'attività TV

Un'applicazione destinata a essere eseguita su dispositivi TV deve dichiarare un'attività di avvio per la TV nel file manifest. A questo scopo, utilizza un filtro per intent CATEGORY_LEANBACK_LAUNCHER. Questo filtro identifica la tua app come abilitata per la TV e consente a Google Play di identificarla come app per la 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 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 manifest delle attività in questo esempio specifica che si tratta dell'attività da avviare su un dispositivo TV.

Attenzione: se non includi il filtro per intent CATEGORY_LEANBACK_LAUNCHER nell'app, significa che non è visibile agli utenti che utilizzano Google Play sui dispositivi TV. Inoltre, se l'app non presenta 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 relativa alla TV dell'app esistente, deve fornire un'interfaccia semplice per una facile navigazione utilizzando un telecomando da una distanza di 3 metri. Se stai modificando un'app esistente da utilizzare sulla TV, non usare per la TV lo stesso layout delle attività che usi per smartphone e tablet. Per le linee guida sulla progettazione di un'app per la TV, vedi Progettare un'app per la TV. Per ulteriori informazioni sui requisiti minimi di implementazione per i layout dell'interfaccia sulla TV, consulta la pagina Creare layout per la TV.

Dichiara il supporto dei dispositivi TV

Dichiara che la tua app è realizzata per Android TV dichiarando la funzionalità android.software.leanback.

Se l'app viene eseguita sia su dispositivi mobili sia 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>

Dichiara il touchscreen non richiesto

Le applicazioni destinate all'esecuzione su dispositivi TV non si basano su touchscreen per l'input. Per chiarire, il file manifest dell'app TV deve dichiarare che la funzionalità android.hardware.touchscreen non è obbligatoria. Questa impostazione identifica la tua app come in grado di funzionare su un dispositivo TV ed è necessaria affinché la tua app venga considerata un'app TV in Google Play. L'esempio di codice che segue 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 è richiesto un touchscreen, come mostrato in questo codice di esempio. In caso contrario, l'app non verrà visualizzata in Google Play sui dispositivi TV.

Fornisci un'icona e un banner della schermata Home

Le app Android TV devono contenere un'icona della schermata Home e un'immagine banner per ogni localizzazione. A seconda del dispositivo Android TV, l'icona o il banner vengono utilizzati come punto di avvio dell'app che viene 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 Android, devono fornire un'icona della schermata Home. Per le best practice su come trovare un ottimo punto di lancio per la tua app e i requisiti dettagliati per gli asset, consulta le linee guida relative ai banner e all'icona dell'app 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 px. 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.

Modifica del colore dell'Avvio app

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

All'avvio di un'app per TV, il sistema visualizza un'animazione che assomiglia a un cerchio pieno che si espande. Per personalizzare il colore di questa animazione, imposta l'attributo android:colorPrimary dell'attività o dell'app TV su un colore specifico. Inoltre, imposta due attributi di sovrapposizione delle transizioni su true, come mostrato nel seguente snippet da un file XML di risorse 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 su come lavorare con temi e stili, consulta la pagina Stili e temi.

Crea un'app per il sistema operativo Android TV

Jetpack include librerie di pacchetti androidx da utilizzare con le app TV.

Scrivi per la TV

Scrivi è il modo consigliato per creare app per il sistema operativo Android TV. Oltre alle librerie Compose principali, le librerie di Compose per TV forniscono componenti dedicati progettati appositamente per lo schermo di casa:

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

Toolkit dell'interfaccia utente di Leanback

Il toolkit dell'interfaccia utente di Leanback fornisce API e widget dell'interfaccia utente per i dispositivi TV:

Scopri come creare un'app per la TV usando il toolkit dell'interfaccia utente di Leanback in Creare app per la riproduzione di contenuti TV.

Esegui app TV

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

Eseguire 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 più volte finché non viene visualizzato 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 la tua applicazione sul tuo dispositivo TV:

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

Esegui su un dispositivo virtuale

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 dispositivi.
  3. Seleziona una delle definizioni del 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 ottenere le migliori prestazioni dell'emulatore TV, utilizza l'emulatore x86 e attiva l'opzione Usa GPU host. Usa anche l'accelerazione del dispositivo virtuale, quando è disponibile. Per maggiori informazioni sull'accelerazione hardware dell'emulatore, consulta la pagina Configurare l'accelerazione hardware per l'emulatore Android.

Per testare la tua 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 del deployment, seleziona il dispositivo TV virtuale e fai clic su OK.

Per maggiori informazioni sull'utilizzo degli emulatori, vedi Eseguire app sull'emulatore Android. Per ulteriori informazioni sull'implementazione di app da Android Studio ai dispositivi virtuali, consulta la pagina Eseguire il debug dell'app.

Attiva l'app TV in modo che venga eseguita come app istantanea

Le esperienze istantanee consentono agli utenti di provare facilmente la tua app TV e contribuiscono ad aumentarne l'adozione.

Per configurare l'esecuzione dell'app TV 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 relativo all'elemento MainActivity della tua app TV, assicurati che entrambi i valori 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>

La tua app TV è ora configurata per funzionare come app istantanea.

Preparare l'app TV per la pubblicazione

Leggi l'elenco di controllo delle app TV per conoscere i passaggi successivi per preparare la tua app per la TV alla pubblicazione e alla distribuzione.

Avanti
AndroidX TV libraries