Creare ed eseguire un'app TV

Le app TV utilizzano la stessa struttura delle app per smartphone e tablet. Questa somiglianza significa che puoi modificare le app esistenti in modo che vengano eseguite anche sui dispositivi TV o creare nuove app basate su 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 l'ambiente di sviluppo per la creazione di app TV e le modifiche minime richieste per consentire l'esecuzione di un'app sui dispositivi TV.

Per informazioni sulla progettazione di app per la TV, consulta Progettare per la TV. Consulta anche le app di esempio nel repository GitHub di Android TV.

Determinare il supporto del formato multimediale

Per informazioni sui codec, i protocolli e i formati supportati da Android TV, consulta la seguente documentazione:

• Formati multimediali supportati
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

Configurare un progetto TV

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

Quando crei un'app che viene eseguita sui dispositivi TV, utilizzi due componenti principali:

• Attività per la TV: nel file manifest dell'applicazione, dichiara un'attività destinata all'esecuzione sui dispositivi TV.
• Librerie TV: facoltativamente, 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 di interfacce utente.

Prerequisiti

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

• Aggiorna gli strumenti 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 della piattaforma aggiornata fornisce nuove API per le app TV.
• Crea o aggiorna il progetto dell'app.
  Per accedere alle nuove API per i dispositivi TV, crea un progetto o modifica un progetto esistente che abbia come target Android 5.0 (livello API 21) o versioni successive.

Dichiarare un'attività TV

Un'applicazione destinata all'esecuzione sui dispositivi TV deve dichiarare un'attività di avvio per la TV nel relativo file manifest. A questo scopo, utilizza un filtro di intent CATEGORY_LEANBACK_LAUNCHER. Questo filtro identifica la tua app come abilitata 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 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 dell'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 nella tua app, gli utenti che eseguono Google Play sui dispositivi TV non la vedranno. Inoltre, se la tua app non ha questo filtro quando utilizzi gli strumenti di sviluppo 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 una navigazione intuitiva utilizzando un telecomando da 3 metri di distanza. Se stai modificando un'app esistente per l'utilizzo sulla TV, non utilizzare lo stesso layout di attività per la TV che utilizzi per smartphone e tablet. Per le linee guida sulla progettazione di un'app per la TV, consulta Progettare per la TV.

Dichiarare il supporto dei dispositivi TV

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

Se la tua 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 su Android TV OS.

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

Dichiarare il touchscreen come non richiesto

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

Fornire un'icona e un banner per la 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 all'app, descrivi l'icona e il banner nel file manifest nel seguente modo:

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

Icona della schermata Home

Le app per Android TV, come tutte le app Android, devono fornire un'icona della schermata Home. Per le best practice sulla progettazione di un ottimo punto di avvio per la tua app e per i requisiti dettagliati delle risorse, consulta le linee guida relative ai banner e all'icona dell'app per Android TV.

Banner della schermata Home

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

Per il banner, utilizza una risorsa xhdpi di dimensioni 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.

Modificare il colore del launcher

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

Quando viene avviata un'app TV, il sistema visualizza un'animazione che assomiglia a un cerchio pieno in espansione. Per personalizzare il colore di questa animazione, imposta l'attributo android:colorPrimary dell'app TV o dell'attività su un colore specifico. Inoltre, imposta su true due attributi di sovrapposizione della transizione, come mostrato nel seguente snippet di un file XML di risorse del tema:

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

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

Creare un'app per Android TV OS

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

Compose for TV

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

• androidx.tv.foundation
• androidx.tv.material

Scopri come creare un'app TV utilizzando Compose for TV in Utilizzare Jetpack Compose su Android TV.

Toolkit UI Leanback

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

• androidx.leanback.app
• androidx.leanback.database
• androidx.leanback.graphics
• androidx.leanback.media
• androidx.leanback.preference
• androidx.leanback.system
• androidx.leanback.widget
• androidx.leanback.widget.picker

Scopri come creare un'app TV utilizzando il toolkit UI Leanback in Creare app di riproduzione TV.

Eseguire 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 dispositivi TV virtuali.

Eseguire su un dispositivo fisico

Configura il dispositivo TV nel seguente modo:

1. Utilizza un cavo USB per collegare il dispositivo TV alla macchina 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 Build e seleziona Build 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 Attiva.
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 target di deployment, seleziona il dispositivo TV e fai clic su OK.

Eseguire su un dispositivo virtuale

Gestione AVD nell'SDK Android fornisce definizioni di dispositivi che ti consentono di creare dispositivi TV virtuali per eseguire e testare le tue applicazioni.

Per creare un dispositivo TV virtuale:

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

   Nota: per prestazioni ottimali del dispositivo emulatore TV, utilizza l'emulatore x86 e attiva l'opzione Usa GPU host. Utilizza anche l'accelerazione del dispositivo virtuale quando è disponibile. Per maggiori informazioni sull'accelerazione hardware dell'emulatore, consulta Configurare l'accelerazione hardware per l' emulatore Android.

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 target di deployment, seleziona il dispositivo TV virtuale e fai clic su OK.

Per maggiori informazioni sull'utilizzo degli emulatori, consulta Eseguire app sull'emulatore Android. Per maggiori informazioni sul deployment di app da Android Studio a dispositivi virtuali, consulta Eseguire il debug dell'app.

Consentire l'esecuzione dell'app TV come app istantanea

Le esperienze istantanee consentono agli utenti di provare l'app TV senza installarla e possono contribuire ad aumentare l'adozione.

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

Poi, nel intent-filter dell'app TV MainActivity, assicurati che sia LAUNCHER sia 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 per preparare l'app TV per la pubblicazione e la distribuzione.