tvOS: sviluppo per Apple TV con Focus Engine

Cos'è tvOS?

tvOS — il sistema operativo Apple per set-top box Apple TV, basato sullo stesso kernel Darwin XNU di iOS. Rilasciato per la prima volta il 30 ottobre 2015 con l'Apple TV di 4a generazione. tvOS ha sostituito il vecchio Apple TV Software (basato su iOS, senza App Store e SDK). Il sistema è ottimizzato per il funzionamento su TV con risoluzione fino a 4K HDR (Dolby Vision) e audio Dolby Atmos.

Secondo Apple (WWDC 2025), tvOS è installato su Apple TV HD (2015), Apple TV 4K (2017, 2021, 2022) e integrato in alcuni modelli di Smart TV tramite AirPlay. Apple TV utilizza chip A8 (HD), A10X Fusion (1a gen 4K), A12 Bionic (2a gen 4K) e A15 Bionic (3a gen 4K). Tutti i modelli supportano tvOS 17. tvOS non ha fotocamera, microfono (tranne il telecomando), schermo touch o GPS.

La caratteristica chiave di tvOS è Focus Engine, che sostituisce il controllo touch con la navigazione a focus. L'utente sposta la selezione tra gli elementi dell'interfaccia utilizzando Siri Remote. Gli sviluppatori creano app in Swift/SwiftUI (native) o JavaScript/TVML (app multimediali come Netflix, Hulu).

Storia delle versioni tvOS

tvOS 9 (2015) — prima versione con SDK e App Store. tvOS 10 (2016) — Single Sign-On (SSO) per abbonamenti via cavo. tvOS 11 (2017) — supporto Amazon Prime Video e modalità automatica. tvOS 12 (2018) — Dolby Atmos. tvOS 13 (2019) — modalità multi-utente. tvOS 17 (2023) — FaceTime, VPN, profili audio via HDMI.

Architettura di tvOS e differenze da iOS

L'architettura di tvOS è basata sullo stesso stack di iOS: kernel XNU, servizi di sistema Core Services, livello Media e livello utente Cocoa Touch. Tuttavia, esistono differenze significative legate alle specificità della piattaforma TV.

Limitazioni hardware

L'Apple TV 4K di 3a generazione utilizza A15 Bionic con 6 core CPU (2 prestazionali, 4 efficienti) e una GPU a 5 core. RAM — 4 GB (storage SSD interno da 64 GB). Il sistema non ha storage locale persistente in senso classico: tutti i dati dell'app possono essere eliminati da tvOS quando lo spazio è insufficiente (purgeable). Lo sviluppatore deve utilizzare iCloud Key-Value Storage o CloudKit per la conservazione dello stato.

TVMLKit e TVJS

TVMLKit — un framework unico per tvOS che consente di creare interfacce in JavaScript e TVML (linguaggio simile a XML specifico di Apple). TVMLKit carica JSON/XML dal server e renderizza componenti UI nativi. Questa è la tecnologia principale per i servizi di streaming: Netflix, Hulu, Amazon Prime Video utilizzano TVMLKit. TVJS — un ambiente JavaScript eseguito in un contesto isolato.

Mancanza di storage persistente

tvOS gestisce automaticamente lo spazio su disco: quando lo spazio è insufficiente, il sistema può eliminare la cache, le risorse scaricate e persino l'app stessa (mantenendo l'icona). Alla riapertura, l'app deve ripristinare il suo stato. iCloud NSUbiquitousKeyValueStore è l'unico storage persistente garantito per le impostazioni (fino a 1 MB per app).

import Foundation

// // Conservazione e ripristino dello stato in tvOS
final class StateManager {

    private let store = NSUbiquitousKeyValueStore.default
    private let coder = JSONEncoder()
    private let decoder = JSONDecoder()

    // Salvataggio progresso visione
    func saveProgress<T: Codable>(_ value: T, for key: String) {
        if let data = try? coder.encode(value) {
            store.set(data, for: key)
            store.synchronize()
        }
    }

    // Ripristino stato dopo eliminazione cache
    func restoreProgress<T: Codable>(_ type: T.Type, for key: String) -> T? {
        guard let data = store.data(for: key) else { return nil }
        return try? decoder.decode(type, from: data)
    }

    // Gestione notifica modifica su altro dispositivo
    init() {
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(ubiquitousKeyValueStoreDidChange),
            name: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
            object: store
        )
    }

    @objc
    private func ubiquitousKeyValueStoreDidChange(_ notification: Notification) {
        print("Dati modificati su altro dispositivo")
    }
}

StateManager utilizza NSUbiquitousKeyValueStore per salvare lo stato dell'app su tvOS. Poiché lo storage locale può essere cancellato dal sistema, solo iCloud garantisce la persistenza dei dati. store.synchronize() invia immediatamente i dati al server, mentre didChangeExternallyNotification notifica l'app delle modifiche da altri dispositivi dell'utente.

Focus Engine: navigazione e focus

Focus Engine — il meccanismo chiave di tvOS che sostituisce gli eventi touch con la navigazione a focus. L'utente sposta la selezione tra gli elementi dell'interfaccia utilizzando Siri Remote (superficie touch o pulsanti). Il sistema calcola automaticamente l'elemento di focus successivo in base alla distanza e alla direzione del movimento.

UIFocusEnvironment e gerarchia del focus

Ogni elemento UI in grado di ricevere il focus implementa il protocollo UIFocusEnvironment. UIKit determina automaticamente l'ordine di navigazione in base alla geometria degli elementi. Lo sviluppatore può sovrascrivere il focus preferito tramite preferredFocusEnvironments, specificare un array di focusEnvironment figli e controllare il movimento tramite UIFocusHeading (up, down, left, right). UIFocusGuide consente di impostare percorsi personalizzati per layout non banali.

UIFocusEffect e parallasse

tvOS aggiunge automaticamente UIFocusEffect all'elemento focalizzato: ombra, evidenziazione ed effetto parallasse (spostamento quando si inclina il telecomando). Lo sviluppatore può disabilitare l'effetto tramite focusedValue o personalizzarlo tramite UIFocusEffect.transform. In SwiftUI, la parallasse viene aggiunta con il modificatore .hoverEffect(.highlight).

import SwiftUI

// // Componente tvOS con focus personalizzato
struct MovieCardView: View {
    let movie: Movie
    @State private var isFocused = false
    @Environment(\.isFocused) var envFocused

    var body: some View {
        VStack(spacing: 8) {
            AsyncImage(url: movie.posterURL) { phase in
                if let image = phase.image {
                    image
                        .resizable()
                        .aspectRatio(contentMode: .fill)
                        .frame(width: 320, height: 180)
                        .cornerRadius(8)
                        .overlay(
                            RoundedRectangle(cornerRadius: 8)
                                .stroke(isFocused ? Color.blue : Color.clear, lineWidth: 3)
                        )
                        .scaleEffect(isFocused ? 1.08 : 1.0)
                }
            }

            Text(movie.title)
                .font(.caption)
                .lineLimit(2)
                .foregroundStyle(isFocused ? .white : .gray)
        }
        .onHover { hovering in
            withAnimation(.spring(response: 0.35)) {
                isFocused = hovering
            }
        }
        .onPlayPauseCommand {
            // Gestione pulsante Play/Pause sul telecomando
            startPlayback()
        }
        .focusable()
        .focusEffect { phase in
            // Effetto focus personalizzato
            phase == .active ?
                AnyView(self.scaleEffect(1.08)) :
                AnyView(self.scaleEffect(1.0))
        }
    }

    private func startPlayback() {
        print("Riproduzione: \(movie.title)")
    }
}

// // Schermata principale con griglia film
struct MovieGridScreen: View {
    let movies: [Movie]

    var body: some View {
        ScrollView {
            LazyVGrid(columns: [GridItem(.adaptive(minimum: 320, maximum: 400))], spacing: 24) {
                ForEach(movies) { movie in
                    MovieCardView(movie: movie)
                }
            }
            .padding(60)
        }
        .focusSection() // Raggruppamento per la navigazione
    }
}

MovieCardView dimostra Focus Engine in SwiftUI: il modificatore .focusable() rende l'elemento focalizzabile, .onHover tiene traccia dei cambiamenti di stato, .focusEffect consente animazioni di focus personalizzate. .onPlayPauseCommand gestisce la pressione del pulsante Play/Pause su Siri Remote. focusSection raggruppa una griglia per la navigazione ciclica.

Siri Remote: gesti e pulsanti

Il Siri Remote di seconda generazione (2021) ha una superficie touch, 5 pulsanti e un microfono. tvOS supporta i gesti: scorrimenti (navigazione), tocco (selezione), doppio tocco (centratura), pizzico-zoom (immagini), pressione lunga (menu contestuale). UIPress con tipi .select, .playPause, .menu, .upArrow, .downArrow, .leftArrow, .rightArrow — tipi di pressione predefiniti. Il microfono del telecomando viene utilizzato per Siri e la ricerca vocale.

Top Shelf e schermata delle app

Top Shelf è un'area sulla schermata Home di Apple TV che mostra il contenuto dinamico dell'app quando si trova nella riga superiore. In tvOS 17, Top Shelf supporta fino a 8 widget con sfondi personalizzati ed elementi interattivi. Lo sviluppatore implementa TVTopShelfProvider per fornire contenuto.

Stili di Top Shelf

Sono disponibili tre stili di Top Shelf: Sectioned — elenco categorizzato (serie per genere), Inset — elemento centrale con descrizione dettagliata (film consigliato), Photo — griglia di immagini (album fotografici). Il sistema aggiorna Top Shelf in background tramite BGTaskScheduler, simile a watchOS. Il provider deve restituire il contenuto rapidamente — tvOS memorizza nella cache i dati per 24 ore.

Schermata delle app

La schermata Home di tvOS è composta da una riga Top Shelf e una griglia di app. Gli utenti possono riorganizzare le icone e creare cartelle. tvOS scarica automaticamente le app dalla memoria quando le risorse sono scarse, quindi lo sviluppatore deve gestire correttamente UISceneDidDisconnectNotification e ripristinare lo stato al riavvio.

SwiftUI per Apple TV

SwiftUI è completamente supportato in tvOS a partire da tvOS 13. Apple raccomanda SwiftUI per tutti i nuovi progetti. Lo stesso codice SwiftUI funziona su iOS, iPadOS, macOS e tvOS con adattamenti minimi per Focus Engine. SwiftUI per tvOS fornisce i modificatori .focusable(), .focusSection(), .onPlayPauseCommand e .onExitCommand.

Adattamento a tvOS

Quando si porta un'app iOS su tvOS, è necessario: sostituire TabView con NavigationView con navigazione a focus, aumentare le dimensioni dei caratteri (minimo 30pt per i titoli, 22pt per il testo), aggiungere margini (minimo 40pt dai bordi — area sicura sui televisori). tvOS non supporta UIAlertController con campo di testo, UIWebView e MFMailComposeViewController.

Raccomandazioni di design

Apple HIG per tvOS: dimensione minima dell'area touch 60×60 punti, testo leggibile da 3 metri (dimensione carattere non inferiore a 22pt per il corpo), contrasto del testo 4.5:1, sfondo scuro (lo sfondo chiaro provoca riflessi sui TV OLED), tutti gli elementi accessibili senza gesti complessi. Risoluzione: Apple TV 4K produce 3840×2160 (4K) o 1920×1080 (HD) a 60 FPS. Tutte le immagini devono essere @2x (per 1080p) e @4x (per 4K).

TVMLKit e applicazioni multimediali

TVMLKit — un framework per creare app multimediali su tvOS utilizzando tecnologie web: JavaScript (TVJS) e TVML (XML specifico di Apple). Le app TVMLKit non richiedono compilazione — l'interfaccia viene caricata dal server, consentendo aggiornamenti dei contenuti senza passare dall'App Review. Viene utilizzato dai principali servizi di streaming per i caroselli di contenuti.

TVML: struttura dei template

TVML fornisce template pronti: CatalogTemplate (catalogo con sezioni), ProductTemplate (pagina dettaglio contenuto), FormTemplate (moduli di login), LoadingTemplate (indicatore di caricamento). I template sono descritti in XML e stilizzati tramite attributi simili a CSS. Il codice TVJS gestisce le pressioni e chiama le API native.

<!-- CatalogTemplate — catalogo dei film su TVML -->
<document>
  <catalogTemplate>
    <banner>
      <title>Novità del cinema</title>
      <description>Anteprime fresche ed esclusive</description>
    </banner>
    <section>
      <header>
        <title>Popolari</title>
      </header>
      <items>
        <lockup>
          <img src="https://cdn.example.com/movie1.jpg" width=300 height=450/>
          <title>Interstellar</title>
        </lockup>
        <lockup>
          <img src="https://cdn.example.com/movie2.jpg" width=300 height=450/>
          <title>Inception</title>
        </lockup>
      </items>
    </section>
  </catalogTemplate>
</document>

Il template TVML CatalogTemplate contiene un banner con titolo e sezioni con elementi lockup. Ogni lockup è una scheda film con immagine e titolo. Focus Engine gestisce automaticamente la navigazione tra gli elementi lockup. Alla pressione, il gestore TVJS riceve l'evento select e può visualizzare una pagina di dettaglio tramite ProductTemplate.

TVJS: gestione eventi

TVJS è un ambiente JavaScript isolato dall'app principale. Il codice TVJS viene chiamato durante il caricamento di un template TVML e la gestione degli eventi. TVJS ha accesso alle API native tramite Appliance e Player per il controllo della riproduzione video. Apple raccomanda di utilizzare TVMLKit solo per app multimediali con aggiornamenti frequenti dei contenuti. Per giochi e app interattive, SwiftUI è preferibile.

Pubblicazione di app tvOS

Pubblicare un'app tvOS richiede un abbonamento Apple Developer Program ($99/anno). L'app viene caricata tramite App Store Connect come prodotto separato o come parte di un binario universale (iOS + tvOS). L'App Review verifica stabilità, conformità HIG e il limite di dimensione di 4 GB.

Build e distribuzione

Xcode crea un target tvOS con estensione .app (pacchetto .ipa). Architettura — arm64 (Apple TV utilizza chip ARM Apple Silicon). tvOS non supporta framework con i386 o x86_64. L'app viene firmata con un certificato Apple Development (test) o Apple Distribution (pubblicazione). È possibile la distribuzione tramite Volume Purchase Program per clienti business.

Requisiti App Review

Requisiti speciali tvOS: tutti gli elementi dell'interfaccia devono essere accessibili tramite Focus Engine senza utilizzare touch screen o tastiera. Le app che richiedono autorizzazione devono supportare Single Sign-On (SSO) tramite iTunes Store. Il contenuto pubblicitario non può interrompere la riproduzione senza il consenso dell'utente. La dimensione del binario caricato non deve superare 4 GB.