Guida introduttiva alle app per TV

Le app per 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 crearne di nuove in base a ciò che già sai sulla creazione di app per Android.

Importante: per poter essere considerata un'app per Android TV su Google Play, la tua app deve soddisfare requisiti specifici. 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 per la TV e quali sono le modifiche minime necessarie per consentire l'esecuzione di un'app sui dispositivi TV.

Per informazioni sulla progettazione di app per la TV, consulta gli articoli Progettare per la TV e Creare layout per la TV. Per esaminare un'app per TV di esempio, vedi l'app Android Leanback 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 per eseguirla sui dispositivi TV o creando una nuova app per TV. Se hai già un'app per Android, aggiungere il supporto di Android TV ti consente di progettare un'interfaccia utente per la TV riutilizzando l'architettura dell'app esistente.

I componenti principali che utilizzi durante la creazione di un'app eseguita sui dispositivi TV sono due:

  • Attività per la TV: nel file manifest dell'applicazione, dichiara un'attività che deve essere eseguita 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 sviluppare un'app per la TV, procedi nel seguente modo:

  • 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 per 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 all'esecuzione 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 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, non sarà visibile agli utenti che utilizzano Google Play sui dispositivi TV. Inoltre, se l'app non dispone di 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 che consenta una facile navigazione utilizzando un telecomando da una distanza di 3 metri. Se stai modificando un'app esistente per utilizzarla sulla TV, non usare per la TV lo stesso layout di attività che usi per telefoni e tablet. Per le linee guida sulla progettazione di un'app per la TV, consulta l'articolo Progettare per la TV. Per ulteriori informazioni sui requisiti minimi di implementazione dei layout dell'interfaccia sulla TV, consulta Creare layout per la TV.

Dichiara il supporto di Leanback

Dichiara che la tua app utilizza l'interfaccia utente Leanback richiesta da Android TV. Se la tua app funziona su dispositivi mobili e su Android TV, imposta il valore dell'attributo required su false. Se imposti il valore dell'attributo required su true, la tua app può essere eseguita solo su dispositivi che utilizzano la UI di Leanback.

<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, nel file manifest dell'app TV deve essere indicato che la funzionalità android.hardware.touchscreen non è obbligatoria. Questa impostazione identifica la tua app come compatibile con un dispositivo TV ed è necessaria che la tua app venga considerata un'app per 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 codice di esempio. In caso contrario, l'app non verrà visualizzata in Google Play sui dispositivi TV.

Fornire un'icona e un banner nella schermata Home

Le app Android TV devono fornire sia un'icona della schermata Home sia 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 visualizzato nella schermata Home nelle righe di app e giochi.

Per aggiungerle 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 per Android TV, come tutte le app per Android, devono fornire un'icona nella schermata Home. Per le best practice su come trovare un ottimo punto di lancio per la tua app e i requisiti dettagliati degli 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 con dimensioni di 320 x 180 px. Il testo deve essere incluso nell'immagine. Se l'app è disponibile in più lingue, devi fornire versioni separate del banner con testo per ogni lingua supportata.

Modifica del colore in Avvio applicazioni

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 Android TV.

All'avvio di un'app per 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'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 sull'utilizzo di temi e stili, consulta la pagina Stili e temi.

Aggiungi raccolte TV

Jetpack include librerie di pacchetti androidx da utilizzare con le app per TV. Queste librerie forniscono API e widget dell'interfaccia utente per i dispositivi TV:

Crea app per la TV

Dopo aver completato i passaggi elencati in precedenza, è il momento di iniziare a creare app per lo schermo di casa. Dai un'occhiata a questi argomenti aggiuntivi che ti aiuteranno a creare la tua app per la TV:

  • Sviluppare app per la riproduzione della TV. Le TV sono progettate per l'intrattenimento, pertanto Android fornisce una serie di strumenti e widget dell'interfaccia utente per creare app per TV che riproducono video e musica e permettono agli utenti di sfogliare i contenuti che preferiscono.
  • Aiutare gli utenti a trovare i tuoi contenuti su Android TV: con la scelta dei contenuti a disposizione degli utenti, aiutarli a trovare i contenuti di loro gradimento è quasi importante quanto fornire questi contenuti. Questa guida spiega come mostrare i tuoi contenuti sui dispositivi TV.
  • Crea giochi per la TV: i dispositivi TV sono un'ottima piattaforma per i giochi. Consulta questo argomento per avere informazioni su come creare esperienze di gioco straordinarie per la TV.
  • Sviluppare servizi di input TV: presenta i tuoi contenuti video in stile lineare, "trasmetti TV", con canali e programmi a cui gli utenti possono accedere tramite una guida ai programmi, nonché con i pulsanti Canale su o giù.

Eseguire app TV

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

Esegui su un dispositivo reale

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 verso il basso fino a Crea e seleziona Crea diverse 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 l'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 la destinazione del deployment, seleziona il dispositivo TV e fai clic su OK.

Esegui su un dispositivo virtuale

AVD Manager nell'SDK Android fornisce definizioni di 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 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 del dispositivo 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, 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 nella barra degli strumenti.
  2. Nella finestra Seleziona la 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 sul deployment delle app da Android Studio ai dispositivi virtuali, consulta la pagina Eseguire il debug dell'app.

Attiva l'esecuzione dell'app TV come app istantanea

Le esperienze istantanee consentono agli utenti di provare facilmente la tua app per 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 prima le istruzioni per creare un app bundle ad attivazione istantanea.

Quindi, in intent-filter per l'MainActivity dell'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 essere eseguita come app istantanea.

Preparare l'app TV per la pubblicazione

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