tvOS: desenvolvimento para Apple TV com Focus Engine

O que é tvOS?

tvOS — sistema operacional da Apple para set-top boxes Apple TV, baseado no mesmo kernel Darwin XNU do iOS. Lançado pela primeira vez em 30 de outubro de 2015 com o Apple TV de 4ª geração. O tvOS substituiu o obsoleto Apple TV Software (baseado em iOS, sem App Store e SDK). O sistema é otimizado para operação em TV com resolução de até 4K HDR (Dolby Vision) e som Dolby Atmos.

De acordo com a Apple (WWDC 2025), o tvOS está instalado no Apple TV HD (2015), Apple TV 4K (2017, 2021, 2022) e integrado em alguns modelos de Smart TV via AirPlay. O Apple TV usa chips A8 (HD), A10X Fusion (1ª geração 4K), A12 Bionic (2ª geração 4K) e A15 Bionic (3ª geração 4K). Todos os modelos suportam tvOS 17. O tvOS não tem câmera, microfone (exceto o controle), tela sensível ao toque ou GPS.

A principal característica do tvOS é o Focus Engine, que substitui o controle por toque pela navegação por foco. O usuário move a seleção entre elementos da interface usando o Siri Remote. Os desenvolvedores criam aplicativos em Swift/SwiftUI (nativos) ou JavaScript/TVML (aplicativos de mídia como Netflix, Hulu).

Histórico de versões do tvOS

tvOS 9 (2015) — primeira versão com SDK e App Store. tvOS 10 (2016) — login único (SSO) para assinaturas de TV a cabo. tvOS 11 (2017) — suporte ao Amazon Prime Video e modo automático. tvOS 12 (2018) — Dolby Atmos. tvOS 13 (2019) — modo multiusuário. tvOS 17 (2023) — FaceTime, VPN, perfis de áudio via HDMI.

Arquitetura do tvOS e diferenças do iOS

A arquitetura do tvOS é baseada na mesma pilha que o iOS: kernel XNU, serviços de sistema Core Services, camada de mídia Media e camada de usuário Cocoa Touch. No entanto, existem diferenças significativas relacionadas às especificidades da plataforma de TV.

Limitações de hardware

O Apple TV 4K de 3ª geração usa A15 Bionic com 6 núcleos de CPU (2 de desempenho, 4 de eficiência) e GPU de 5 núcleos. RAM — 4 GB (armazenamento SSD interno a partir de 64 GB). O sistema não possui armazenamento local persistente no sentido clássico: todos os dados do aplicativo podem ser excluídos pelo tvOS quando o espaço está baixo (purgeable). O desenvolvedor deve usar iCloud Key-Value Storage ou CloudKit para preservação do estado.

TVMLKit e TVJS

TVMLKit — um framework único do tvOS que permite criar interfaces em JavaScript e TVML (linguagem semelhante a XML específica da Apple). O TVMLKit carrega JSON/XML do servidor e renderiza componentes de interface nativos. Esta é a principal tecnologia para serviços de streaming: Netflix, Hulu, Amazon Prime Video usam TVMLKit. TVJS — um ambiente JavaScript executado em contexto isolado.

Falta de armazenamento persistente

O tvOS gerencia automaticamente o espaço em disco: quando o espaço está baixo, o sistema pode excluir cache, recursos baixados e até o próprio aplicativo (mantendo o ícone). Ao reabrir, o aplicativo deve restaurar seu estado. O iCloud NSUbiquitousKeyValueStore é o único armazenamento persistente garantido para configurações (até 1 MB por aplicativo).

import Foundation

// // Preservação e restauração de estado no tvOS
final class StateManager {

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

    // Salvando progresso de visualização
    func saveProgress<T: Codable>(_ value: T, for key: String) {
        if let data = try? coder.encode(value) {
            store.set(data, for: key)
            store.synchronize()
        }
    }

    // Restaurando estado após exclusão de 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)
    }

    // Manipulando notificação de mudança em outro dispositivo
    init() {
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(ubiquitousKeyValueStoreDidChange),
            name: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
            object: store
        )
    }

    @objc
    private func ubiquitousKeyValueStoreDidChange(_ notification: Notification) {
        print("Dados alterados em outro dispositivo")
    }
}

O StateManager usa NSUbiquitousKeyValueStore para salvar o estado do aplicativo no tvOS. Como o armazenamento local pode ser limpo pelo sistema, apenas o iCloud garante a persistência dos dados. store.synchronize() envia dados imediatamente para o servidor, enquanto didChangeExternallyNotification notifica o aplicativo sobre mudanças de outros dispositivos do usuário.

Focus Engine: navegação e foco

Focus Engine — o mecanismo chave do tvOS que substitui eventos de toque pela navegação por foco. O usuário move a seleção entre elementos da interface usando o Siri Remote (superfície tátil ou botões). O sistema calcula automaticamente o próximo elemento de foco com base na distância e direção do movimento.

UIFocusEnvironment e hierarquia de foco

Cada elemento de interface capaz de receber foco implementa o protocolo UIFocusEnvironment. O UIKit determina automaticamente a ordem de navegação com base na geometria dos elementos. O desenvolvedor pode substituir o foco preferido via preferredFocusEnvironments, especificar um array de focusEnvironment filhos e controlar o movimento através de UIFocusHeading (up, down, left, right). UIFocusGuide permite definir rotas personalizadas para layouts não triviais.

UIFocusEffect e paralaxe

O tvOS adiciona automaticamente UIFocusEffect ao elemento focado: sombra, destaque e efeito de paralaxe (deslocamento ao inclinar o controle). O desenvolvedor pode desativar o efeito via focusedValue ou personalizá-lo através de UIFocusEffect.transform. Em SwiftUI, a paralaxe é adicionada com o modificador .hoverEffect(.highlight).

import SwiftUI

// // Componente tvOS com foco personalizado
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 {
            // Manipulando botão Play/Pause no controle
            startPlayback()
        }
        .focusable()
        .focusEffect { phase in
            // Efeito de foco personalizado
            phase == .active ?
                AnyView(self.scaleEffect(1.08)) :
                AnyView(self.scaleEffect(1.0))
        }
    }

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

// // Tela principal com grade de filmes
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() // Agrupamento para navegação
    }
}

MovieCardView demonstra o Focus Engine em SwiftUI: o modificador .focusable() torna o elemento focalizável, .onHover rastreia mudanças de estado, .focusEffect permite animação de foco personalizada. .onPlayPauseCommand lida com o pressionamento do botão Play/Pause no Siri Remote. focusSection agrupa uma grade para navegação cíclica.

Siri Remote: gestos e botões

O Siri Remote de segunda geração (2021) tem uma superfície tátil, 5 botões e um microfone. O tvOS suporta gestos: deslizes (navegação), toque (selecionar), toque duplo (centralizar), pinça-zoom (imagens), pressão longa (menu contextual). UIPress com tipos .select, .playPause, .menu, .upArrow, .downArrow, .leftArrow, .rightArrow — tipos de pressão predefinidos. O microfone do controle é usado para Siri e pesquisa por voz.

Top Shelf e tela de aplicativos

Top Shelf é uma área na tela inicial do Apple TV que exibe conteúdo dinâmico do aplicativo quando está na linha superior. No tvOS 17, o Top Shelf suporta até 8 widgets com fundos personalizados e elementos interativos. O desenvolvedor implementa TVTopShelfProvider para fornecer conteúdo.

Estilos de Top Shelf

Três estilos de Top Shelf estão disponíveis: Sectioned — lista categorizada (séries por gênero), Inset — elemento central com descrição detalhada (filme recomendado), Photo — grade de imagens (álbuns de fotos). O sistema atualiza o Top Shelf em segundo plano via BGTaskScheduler, similar ao watchOS. O provedor deve retornar conteúdo rapidamente — o tvOS armazena dados em cache por 24 horas.

Tela de aplicativos

A tela inicial do tvOS consiste em uma linha Top Shelf e uma grade de aplicativos. Os usuários podem reorganizar ícones e criar pastas. O tvOS descarrega automaticamente os aplicativos da memória quando os recursos estão baixos, portanto, o desenvolvedor deve lidar corretamente com UISceneDidDisconnectNotification e restaurar o estado ao reiniciar.

SwiftUI para Apple TV

SwiftUI é totalmente suportado no tvOS desde o tvOS 13. A Apple recomenda SwiftUI para todos os novos projetos. O mesmo código SwiftUI funciona no iOS, iPadOS, macOS e tvOS com adaptações mínimas para o Focus Engine. O SwiftUI para tvOS fornece os modificadores .focusable(), .focusSection(), .onPlayPauseCommand e .onExitCommand.

Adaptação para tvOS

Ao portar um aplicativo iOS para tvOS, é necessário: substituir TabView por NavigationView com navegação por foco, aumentar o tamanho das fontes (mínimo 30pt para títulos, 22pt para texto), adicionar margens (mínimo 40pt das bordas — área segura em TVs). tvOS não suporta UIAlertController com campo de texto, UIWebView ou MFMailComposeViewController.

Recomendações de design

HIG da Apple para tvOS: tamanho mínimo da área tátil 60×60 pontos, texto legível a 3 metros (tamanho da fonte não inferior a 22pt para corpo), contraste de texto 4.5:1, fundo escuro (fundo claro causa reflexos em TVs OLED), todos os elementos acessíveis sem gestos complexos. Resolução: Apple TV 4K produz 3840×2160 (4K) ou 1920×1080 (HD) a 60 FPS. Todas as imagens devem ser @2x (para 1080p) e @4x (para 4K).

TVMLKit e aplicativos de mídia

TVMLKit — um framework para criar aplicativos de mídia no tvOS usando tecnologias web: JavaScript (TVJS) e TVML (XML específico da Apple). Os aplicativos TVMLKit não precisam de compilação — a interface é carregada do servidor, permitindo atualizações de conteúdo sem passar pelo App Review. É usado pelos principais serviços de streaming para carrosséis de conteúdo.

TVML: estrutura de templates

TVML fornece templates prontos: CatalogTemplate (catálogo com seções), ProductTemplate (página de detalhes do conteúdo), FormTemplate (formulários de login), LoadingTemplate (indicador de carregamento). Os templates são descritos em XML e estilizados através de atributos semelhantes a CSS. O código TVJS lida com pressões e chama APIs nativas.

<!-- CatalogTemplate — catálogo de filmes em TVML -->
<document>
  <catalogTemplate>
    <banner>
      <title>Novidades do cinema</title>
      <description>Estreias recentes e exclusividades</description>
    </banner>
    <section>
      <header>
        <title>Popular</title>
      </header>
      <items>
        <lockup>
          <img src="https://cdn.example.com/movie1.jpg" width=300 height=450/>
          <title>Interestelar</title>
        </lockup>
        <lockup>
          <img src="https://cdn.example.com/movie2.jpg" width=300 height=450/>
          <title>A Origem</title>
        </lockup>
      </items>
    </section>
  </catalogTemplate>
</document>

O template TVML CatalogTemplate contém um banner com título e seções com elementos lockup. Cada lockup é um cartão de filme com imagem e título. O Focus Engine gerencia automaticamente a navegação entre elementos lockup. Ao pressionar, o manipulador TVJS recebe o evento select e pode exibir uma página de detalhes via ProductTemplate.

TVJS: manipulação de eventos

TVJS é um ambiente JavaScript isolado do aplicativo principal. O código TVJS é chamado ao carregar um template TVML e manipular eventos. O TVJS tem acesso a APIs nativas através de Appliance e Player para controle de reprodução de vídeo. A Apple recomenda usar TVMLKit apenas para aplicativos de mídia com atualizações frequentes de conteúdo. Para jogos e aplicativos interativos, SwiftUI é preferível.

Publicando aplicativos tvOS

Publicar um aplicativo tvOS requer uma assinatura do Apple Developer Program ($99/ano). O aplicativo é enviado via App Store Connect como um produto separado ou como parte de um binário universal (iOS + tvOS). O App Review verifica estabilidade, conformidade com HIG e o limite de tamanho de 4 GB.

Build e distribuição

O Xcode cria um destino tvOS com extensão .app (pacote .ipa). Arquitetura — arm64 (Apple TV usa chips ARM da Apple Silicon). O tvOS não suporta frameworks com i386 ou x86_64. O aplicativo é assinado com certificado Apple Development (testes) ou Apple Distribution (publicação). Distribuição via Volume Purchase Program para clientes empresariais é possível.

Requisitos do App Review

Requisitos especiais do tvOS: todos os elementos da interface devem ser acessíveis através do Focus Engine sem usar tela sensível ao toque ou teclado. Aplicativos que exigem autorização devem suportar login único (SSO) via iTunes Store. O conteúdo publicitário não pode interromper a reprodução sem o consentimento do usuário. O tamanho do binário enviado não deve exceder 4 GB.