tvOS: tworzenie aplikacji na Apple TV z Focus Engine

Co to jest tvOS?

tvOS — system operacyjny Apple dla dekoderów Apple TV, oparty na tym samym jądrze Darwin XNU co iOS. Wydany po raz pierwszy 30 października 2015 roku z Apple TV 4. generacji. tvOS zastąpił przestarzałe Apple TV Software (oparte na iOS, bez App Store i SDK). System jest zoptymalizowany do pracy na telewizorze z rozdzielczością do 4K HDR (Dolby Vision) i dźwiękiem Dolby Atmos.

Według Apple (WWDC 2025), tvOS jest zainstalowany na Apple TV HD (2015), Apple TV 4K (2017, 2021, 2022) i wbudowany w niektóre modele Smart TV przez AirPlay. Apple TV używa układów A8 (HD), A10X Fusion (1. gen 4K), A12 Bionic (2. gen 4K) i A15 Bionic (3. gen 4K). Wszystkie modele obsługują tvOS 17. tvOS nie ma kamery, mikrofonu (oprócz pilota), ekranu dotykowego ani GPS.

Kluczową cechą tvOS jest Focus Engine, który zastępuje sterowanie dotykowe nawigacją fokusową. Użytkownik przesuwa zaznaczenie między elementami interfejsu za pomocą Siri Remote. Deweloperzy tworzą aplikacje w Swift/SwiftUI (natywne) lub JavaScript/TVML (aplikacje multimedialne Netflix, Hulu).

Historia wersji tvOS

tvOS 9 (2015) — pierwsza wersja z SDK i App Store. tvOS 10 (2016) — pojedyncze logowanie (SSO) dla subskrypcji kablowych. tvOS 11 (2017) — obsługa Amazon Prime Video i tryb automatyczny. tvOS 12 (2018) — Dolby Atmos. tvOS 13 (2019) — tryb wieloużytkownikowy. tvOS 17 (2023) — FaceTime, VPN, profile audio przez HDMI.

Architektura tvOS i różnice od iOS

Architektura tvOS opiera się na tym samym stosie co iOS: jądro XNU, usługi systemowe Core Services, warstwa medialna Media i warstwa użytkownika Cocoa Touch. Istnieją jednak znaczące różnice związane ze specyfiką platformy telewizyjnej.

Ograniczenia sprzętowe

Apple TV 4K 3. generacji używa A15 Bionic z 6 rdzeniami CPU (2 wydajnościowe, 4 energooszczędne) i 5-rdzeniowym GPU. RAM — 4 GB (wewnętrzna pamięć SSD od 64 GB). System nie ma trwałej pamięci lokalnej w klasycznym sensie: wszystkie dane aplikacji mogą zostać usunięte przez tvOS przy braku miejsca (purgeable). Deweloper musi używać iCloud Key-Value Storage lub CloudKit do przechowywania stanu.

TVMLKit i TVJS

TVMLKit — unikalny dla tvOS framework umożliwiający tworzenie interfejsów w JavaScript i TVML (język podobny do XML specyficzny dla Apple). TVMLKit ładuje JSON/XML z serwera i renderuje natywne komponenty interfejsu. Jest to podstawowa technologia dla usług przesyłania strumieniowego: Netflix, Hulu, Amazon Prime Video używają TVMLKit. TVJS — środowisko JavaScript działające w izolowanym kontekście.

Brak trwałego przechowywania

tvOS automatycznie zarządza miejscem na dysku: przy braku miejsca system może usunąć pamięć podręczną, pobrane zasoby, a nawet samą aplikację (zachowując ikonę). Przy ponownym otwarciu aplikacja musi przywrócić swój stan. iCloud NSUbiquitousKeyValueStore to jedyne gwarantowane trwałe przechowywanie ustawień (do 1 MB na aplikację).

import Foundation

// // Zapisywanie i przywracanie stanu w tvOS
final class StateManager {

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

    // Zapisywanie postępu oglądania
    func saveProgress<T: Codable>(_ value: T, for key: String) {
        if let data = try? coder.encode(value) {
            store.set(data, for: key)
            store.synchronize()
        }
    }

    // Przywracanie stanu po usunięciu pamięci podręcznej
    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)
    }

    // Obsługa powiadomienia o zmianie na innym urządzeniu
    init() {
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(ubiquitousKeyValueStoreDidChange),
            name: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
            object: store
        )
    }

    @objc
    private func ubiquitousKeyValueStoreDidChange(_ notification: Notification) {
        print("Dane zmienione na innym urządzeniu")
    }
}

Menedżer StateManager używa NSUbiquitousKeyValueStore do zapisywania stanu aplikacji na tvOS. Ponieważ lokalna pamięć może zostać wyczyszczona przez system, tylko iCloud gwarantuje trwałość danych. store.synchronize() natychmiast wysyła dane na serwer, a didChangeExternallyNotification powiadamia aplikację o zmianach z innych urządzeń użytkownika.

Focus Engine: nawigacja i fokus

Focus Engine — kluczowy mechanizm tvOS, który zastępuje zdarzenia dotykowe nawigacją fokusową. Użytkownik przesuwa zaznaczenie między elementami interfejsu za pomocą Siri Remote (powierzchnia dotykowa lub przyciski). System automatycznie oblicza następny element fokusu na podstawie odległości i kierunku ruchu.

UIFocusEnvironment i hierarchia fokusu

Każdy element interfejsu zdolny do otrzymania fokusu implementuje protokół UIFocusEnvironment. UIKit automatycznie określa kolejność nawigacji na podstawie geometrii elementów. Deweloper może zastąpić preferowany fokus przez preferredFocusEnvironments, określić tablicę podrzędnych focusEnvironment i kontrolować ruch przez UIFocusHeading (up, down, left, right). UIFocusGuide umożliwia ustawienie niestandardowych tras dla nietrywialnych układów.

UIFocusEffect i paralaksa

tvOS automatycznie dodaje UIFocusEffect do sfokusowanego elementu: cień, podświetlenie i efekt paralaksy (przesunięcie przy pochyleniu pilota). Deweloper może wyłączyć efekt przez focusedValue lub dostosować przez UIFocusEffect.transform. W SwiftUI paralaksa jest dodawana modyfikatorem .hoverEffect(.highlight).

import SwiftUI

// // Komponent tvOS z niestandardowym fokusem
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 {
            // Obsługa przycisku Play/Pause na pilocie
            startPlayback()
        }
        .focusable()
        .focusEffect { phase in
            // Niestandardowy efekt fokusu
            phase == .active ?
                AnyView(self.scaleEffect(1.08)) :
                AnyView(self.scaleEffect(1.0))
        }
    }

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

// // Ekran główny z siatką filmów
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() // Grupowanie dla nawigacji
    }
}

MovieCardView demonstruje Focus Engine w SwiftUI: modyfikator .focusable() czyni element fokusowalnym, .onHover śledzi zmiany stanu, .focusEffect umożliwia niestandardową animację fokusu. .onPlayPauseCommand obsługuje naciśnięcie przycisku Play/Pause na Siri Remote. focusSection grupuje siatkę dla nawigacji cyklicznej.

Siri Remote: gesty i przyciski

Siri Remote drugiej generacji (2021) ma powierzchnię dotykową, 5 przycisków i mikrofon. tvOS obsługuje gesty: przesunięcia (nawigacja), dotknięcie (wybór), podwójne dotknięcie (centrowanie), ściśnięcie-zoom (obrazy), długie naciśnięcie (menu kontekstowe). UIPress z typami .select, .playPause, .menu, .upArrow, .downArrow, .leftArrow, .rightArrow — predefiniowane typy naciśnięć. Mikrofon pilota jest używany dla Siri i wyszukiwania głosowego.

Top Shelf i ekran aplikacji

Top Shelf — obszar na ekranie głównym Apple TV wyświetlający dynamiczną zawartość aplikacji, gdy znajduje się ona w górnym rzędzie. W tvOS 17 Top Shelf obsługuje do 8 widżetów z niestandardowym tłem i interaktywnymi elementami. Deweloper implementuje TVTopShelfProvider do dostarczania treści.

Style Top Shelf

Dostępne są trzy style Top Shelf: Sectioned — kategoryzowana lista (seriale według gatunku), Inset — element centralny ze szczegółowym opisem (polecany film), Photo — siatka obrazów (albumy zdjęć). System aktualizuje Top Shelf w tle przez BGTaskScheduler, podobnie jak watchOS. Dostawca musi szybko zwracać treść — tvOS buforuje dane przez 24 godziny.

Ekran aplikacji

Ekran główny tvOS składa się z rzędu Top Shelf i siatki aplikacji. Użytkownicy mogą zmieniać układ ikon i tworzyć foldery. tvOS automatycznie zwalnia aplikacje z pamięci przy braku zasobów, dlatego deweloper musi poprawnie obsługiwać UISceneDidDisconnectNotification i przywracać stan przy ponownym uruchomieniu.

SwiftUI dla Apple TV

SwiftUI jest w pełni obsługiwane w tvOS od tvOS 13. Apple zaleca SwiftUI dla wszystkich nowych projektów. Ten sam kod SwiftUI działa na iOS, iPadOS, macOS i tvOS z minimalnymi adaptacjami do Focus Engine. SwiftUI dla tvOS udostępnia modyfikatory .focusable(), .focusSection(), .onPlayPauseCommand i .onExitCommand.

Adaptacja do tvOS

Podczas przenoszenia aplikacji iOS na tvOS należy: zastąpić TabView NavigationView z nawigacją fokusową, zwiększyć rozmiary czcionek (minimum 30pt dla nagłówków, 22pt dla tekstu), dodać marginesy (minimum 40pt od krawędzi — bezpieczny obszar na telewizorach). tvOS nie obsługuje UIAlertController z polem tekstowym, UIWebView i MFMailComposeViewController.

Zalecenia projektowe

Apple HIG dla tvOS: minimalny rozmiar obszaru dotykowego 60×60 punktów, tekst czytelny z odległości 3 metrów (rozmiar czcionki nie mniejszy niż 22pt dla treści), kontrast tekstu 4.5:1, ciemne tło (jasne tło odbija się na telewizorach OLED), wszystkie elementy dostępne bez skomplikowanych gestów. Rozdzielczość: Apple TV 4K wyświetla 3840×2160 (4K) lub 1920×1080 (HD) przy 60 FPS. Wszystkie obrazy powinny być w @2x (dla 1080p) i @4x (dla 4K).

TVMLKit i aplikacje multimedialne

TVMLKit — framework do tworzenia aplikacji multimedialnych na tvOS z użyciem technologii webowych: JavaScript (TVJS) i TVML (XML specyficzny dla Apple). Aplikacje TVMLKit nie wymagają kompilacji — interfejs jest ładowany z serwera, co pozwala na aktualizacje treści bez przechodzenia przez App Review. Jest używany przez główne usługi przesyłania strumieniowego do karuzel treści.

TVML: struktura szablonów

TVML udostępnia gotowe szablony: CatalogTemplate (katalog z sekcjami), ProductTemplate (strona szczegółów treści), FormTemplate (formularze logowania), LoadingTemplate (wskaźnik ładowania). Szablony są opisane w XML i stylizowane przez atrybuty podobne do CSS. Kod TVJS obsługuje naciśnięcia i wywołuje natywne API.

<!-- CatalogTemplate — katalog filmów na TVML -->
<document>
  <catalogTemplate>
    <banner>
      <title>Nowości filmowe</title>
      <description>Świeże premiery i ekskluzywne treści</description>
    </banner>
    <section>
      <header>
        <title>Popularne</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>Nachalo</title>
        </lockup>
      </items>
    </section>
  </catalogTemplate>
</document>

Szablon TVML CatalogTemplate zawiera baner z tytułem i sekcje z elementami lockup. Każdy lockup to karta filmu z obrazem i tytułem. Focus Engine automatycznie zarządza nawigacją między elementami lockup. Po naciśnięciu program obsługi TVJS otrzymuje zdarzenie select i może wyświetlić stronę szczegółów przez ProductTemplate.

TVJS: obsługa zdarzeń

TVJS to środowisko JavaScript odizolowane od głównej aplikacji. Kod TVJS jest wywoływany podczas ładowania szablonu TVML i obsługi zdarzeń. TVJS ma dostęp do natywnych API przez Appliance i Player do sterowania odtwarzaniem wideo. Apple zaleca używanie TVMLKit tylko dla aplikacji multimedialnych z częstymi aktualizacjami treści. Do gier i aplikacji interaktywnych preferowany jest SwiftUI.

Publikowanie aplikacji tvOS

Publikowanie aplikacji tvOS wymaga subskrypcji Apple Developer Program ($99/rok). Aplikacja jest przesyłana przez App Store Connect jako osobny produkt lub w ramach uniwersalnego pliku binarnego (iOS + tvOS). App Review sprawdza stabilność, zgodność z HIG i limit rozmiaru 4 GB.

Budowanie i dystrybucja

Xcode tworzy cel tvOS z rozszerzeniem .app (pakiet .ipa). Architektura — arm64 (Apple TV używa układów ARM Apple Silicon). tvOS nie obsługuje frameworków z i386 lub x86_64. Aplikacja jest podpisywana certyfikatem Apple Development (testowanie) lub Apple Distribution (publikacja). Możliwa jest dystrybucja przez Volume Purchase Program dla klientów biznesowych.

Wymagania App Review

Specjalne wymagania tvOS: wszystkie elementy interfejsu muszą być dostępne przez Focus Engine bez użycia ekranu dotykowego lub klawiatury. Aplikacje wymagające autoryzacji muszą obsługiwać pojedyncze logowanie (SSO) przez iTunes Store. Treści reklamowe nie mogą przerywać odtwarzania bez zgody użytkownika. Rozmiar przesłanego pliku binarnego nie może przekraczać 4 GB.