Creare ed eseguire un'app TV

Le app TV utilizzano la stessa struttura delle app per smartphone e tablet. Questa somiglianza ti consente di modificare le 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 nella sezione 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, vedi Progettazione 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 spiega come configurare un progetto TV, sia che tu stia modificando un'app per Android esistente per eseguirla su 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 su dispositivi TV, utilizzi due componenti principali:

• Attività per la TV:nel manifest dell'applicazione, dichiara un'attività destinata a essere eseguita su 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 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 dell'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 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 a essere eseguita su dispositivi TV deve dichiarare un'attività di avvio per la TV nel 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 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 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 dell'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, questa non è visibile agli utenti che eseguono 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 sezione 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 dell'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 è pensata per Android TV dichiarando la funzionalità android.software.leanback.

Se la tua 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à la tua app disponibile solo sul sistema operativo Android TV.

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

Dichiarare il touchscreen come non richiesto

Le applicazioni destinate a essere eseguite su dispositivi TV non si basano sui touchscreen per l'input. Per rendere chiaro questo aspetto, 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 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.

Fornisci un'icona e un banner della 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 che viene visualizzato nella schermata Home nelle righe di app e giochi.

Per aggiungerli alla tua app, descrivi l'icona e il banner nel manifest nel seguente modo:

<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 fornire un'icona per la schermata Home. Per le best practice sulla progettazione di un ottimo punto di lancio per la tua app e sui 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 oppure con il tag <activity> 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 dell'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 per Android TV.

Quando viene avviata un'app TV, il sistema mostra un'animazione che assomiglia a un cerchio pieno che si espande. Per personalizzare il colore di questa animazione, imposta l'attributo android:colorPrimary dell'app TV o dell'attività su un colore specifico. Inoltre, imposta due attributi di sovrapposizione della transizione su true 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 saperne di più su come utilizzare temi e stili, consulta Stili e temi.

Crea 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 di base, 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 per la UI di 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 Crea 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.

Esegui su un dispositivo fisico

Configura il tuo dispositivo TV nel seguente modo:

1. Usa 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 seleziona On.
7. Torna alla schermata Home della TV.

Per testare l'applicazione sul tuo dispositivo TV:

1. In Android Studio, seleziona il progetto e fai clic su Esegui dalla barra degli strumenti.
2. Nella finestra Seleziona target di distribuzione, seleziona il tuo dispositivo TV e fai clic su Ok.

Esegui 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 Gestione AVD. Per saperne di più, consulta Crea e gestisci 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 AVD.
4. Seleziona le opzioni dell'emulatore e fai clic su Ok per creare l'AVD.

   Nota:per ottenere le migliori prestazioni 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 ulteriori informazioni sull'accelerazione hardware dell'emulatore, vedi 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 dalla barra degli strumenti.
2. Nella finestra Seleziona target di deployment, seleziona il tuo dispositivo TV virtuale e fai clic su Ok.

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

Consentire l'esecuzione dell'app TV come app istantanea

Le app istantanee consentono agli utenti di provare la tua 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 compatibile con le app istantanee.

Successivamente, in intent-filter per MainActivity della tua app TV, 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 per le app TV per i passaggi successivi per preparare la tua app TV per la pubblicazione e la distribuzione.