Creare ed eseguire un'app TV

Le app TV utilizzano la stessa struttura delle app per smartphone e tablet. Questa somiglianza significa che modificare le app esistenti in modo che vengano eseguite anche sui dispositivi TV o creare nuove app in base alle funzionalità informazioni sulla creazione di app per Android.

Importante:la tua app deve soddisfare requisiti specifici per essere considerate app per Android TV su Google Play. Per ulteriori informazioni, consulta i requisiti elencati nella qualità delle app TV.

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

Per informazioni sulla progettazione di app per la TV, consulta la sezione Progettare per sulla TV. Vedi anche le app di esempio nella Repository GitHub di Android TV.

Determinare il supporto del formato multimediale

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

Configura un progetto TV

In questa sezione viene illustrato come impostare un progetto TV, indipendentemente dal fatto che tu modifica di un'app per Android esistente in modo che venga eseguita sui dispositivi TV o creazione una nuova app TV. Se hai già un'app per Android, il supporto di Android TV ti consente di progettare un'interfaccia utente per la TV riutilizzando l'architettura esistente dell'app.

Quando crei un'app da usare sui dispositivi TV, puoi utilizzare due componenti principali:

  • Attività per TV: nel file manifest dell'applicazione, dichiarare un'attività che deve essere eseguita sui dispositivi TV.
  • Raccolte TV:includi, se vuoi, uno o più dei seguenti elementi librerie androidx disponibili per i dispositivi TV, elencati 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 seguire questi 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 progetto che ha come target Android 5.0 (livello API 21) o versioni successive.

Dichiarare un'attività TV

Un'applicazione destinata a essere eseguita sui dispositivi TV deve dichiarare un'attività di avvio applicazioni per la TV nel suo file manifest. Usa un intent CATEGORY_LEANBACK_LAUNCHER filtro per farlo. Questo filtro identifica la tua app come attiva per la TV e ti consente Google Play la identifichi 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 manifest di attività in questo esempio specifica che è l'attività da avviala su un dispositivo TV.

Attenzione: se non includi i campi CATEGORY_LEANBACK_LAUNCHER filtro per intent in la tua app, non è visibile agli utenti che utilizzano Google Play sui dispositivi TV. Inoltre, se app non dispone di questo filtro quando utilizzi gli strumenti per sviluppatori per caricarla su un dispositivo TV, l'app non viene visualizzato 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 usando un telecomando da 3 metri di distanza. Se stai modificando un'app esistente da usare sulla TV, non usare la stessa app layout dell'attività per la TV su smartphone e tablet. Per le linee guida sulla progettazione di un'app per la TV, consulta la pagina Progettazione per la TV.

Dichiara il supporto dei dispositivi TV

Dichiara che la tua app è destinata ad Android TV dichiarando il 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 soltanto sul sistema operativo Android TV. 

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

Dichiarazione touchscreen non richiesto

Le applicazioni destinate all'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 è obbligatoria. Questa impostazione identifica la tua app come funzionare su un dispositivo TV ed è necessario affinché la tua app sia considerata un'app TV in Google Gioca. 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, la tua app non viene visualizzata in Google Play sulla TV dispositivi mobili.

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 per avviare l'app. visualizzato nella schermata Home nelle righe relative ad 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 un ottimo punto di lancio per la tua app e requisiti dettagliati per gli asset, consulta Icona e banner dell'app Android TV linee guida.

Utilizza la android:banner con <application> , per fornire un banner predefinito per tutte le attività dell'applicazione, o con il <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 nel dell'immagine. Se la tua app è disponibile in più lingue, devi fornire versioni separate delle con testo per ogni lingua supportata.

Modificare il colore di Avvio app

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

All'avvio di un'app TV, il sistema mostra un'animazione simile a un'app riempita che si espande cerchio. Per personalizzare il colore di questa animazione, imposta android:colorPrimary della tua attività o app TV a un colore specifico. Inoltre, imposta due transizione degli attributi di sovrapposizione a true come mostrato nello snippet seguente da un file XML delle 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, vedi 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

Compose è il metodo consigliato per creare app per il sistema operativo Android TV. Insieme al componente principale di Compose librerie Compose per TV, che forniscono componenti dedicati progettati appositamente per i schermo di casa:

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

Toolkit UI Leanback

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

Scopri come creare un'app TV con il toolkit Leanback UI in Realizza app per riprodurre contenuti sulla TV.

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 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 più volte Crea fino a quando non ricevi 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 dispositivo TV:

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

Esegui su un dispositivo virtuale

Gestione AVD in Android L'SDK fornisce definizioni di dispositivi che ti consentono di creare dispositivi TV virtuali per l'esecuzione e per testare le tue applicazioni.

Per creare un dispositivo TV virtuale:

  1. Avvia Gestione AVD. Per ulteriori informazioni, vedi 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 Utilizza GPU host. Usa l'accelerazione dei dispositivi virtuali anche quando disponibili. Per ulteriori informazioni sull'accelerazione hardware dell'emulatore, vedi Configura l'accelerazione hardware per il 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 destinazione deployment, seleziona il tuo dispositivo TV virtuale e fai clic su Ok.

Per ulteriori informazioni sull'uso degli emulatori, vedi Esegui le app sull'emulatore Android. Per ulteriori informazioni sul deployment di app da Android Studio ai computer dispositivi, consulta Eseguire il debug dell'app.

Attiva l'esecuzione dell'app TV come app istantanea

Le esperienze istantanee rendono più semplice per gli utenti per provare la tua app TV e può contribuire 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 crea un app bundle ad attivazione istantanea.

Poi, da intent-filter per l'app TV MainActivity, assicurati che LAUNCHER e LEANBACK_LAUNCHER 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 la tua app TV alla pubblicazione e alla distribuzione.

Avanti
Gestire l'hardware della TV