Planning your tvOS app
If you’re new to Apple TV software development, take a moment to familiarize yourself with the tools and technologies you’ll use. Apple provides the tools you need to get started, and tvOS gives you the technologies and features you want with the performance you need.
Explore the possibilities
Embrace the living-room experience on Apple TV by delivering content people can enjoy from their couch. Stream the latest entertainment, sports, or news content. Offer a great game or education experience, or deliver personal training sessions from a fitness app. Deliver your content in high-quality formats such as 4K video, Dolby Vision, Dolby Atmos, and HDR10. Design your app’s interface to support easy navigation with the Apple TV remote.
tvOS offers different paths for delivering your content, and the path you choose initially affects the decisions you make later:
Assemble your UI from standard views
Build your UI from buttons, text labels, and other standard views and controls in tvOS when your content doesn’t change significantly between releases. Customize the appearance of controls, or create entirely new views to present your content in unique ways. Your UI remains local to Apple TV, and you fill it with data you obtain locally or from the network.
Store your UI and content on your server
Build your UI dynamically from XML templates, JavaScript code, and other content you store on your server. Choose this approach if you update your app’s content regularly. For example, use this approach in a media app that updates the current movie choices each week. Your app downloads content at runtime and assembles your interface.
After you choose the path for your app, think about the other features you might need. Apart from a few core technologies, you can adopt most technologies as necessary to support specific features. Apple offers technologies for managing and playing media, creating and securing data, connecting to external hardware, integrating with system services like Siri, and much more.
Where to start
Software development starts with Xcode — Apple’s integrated development environment. Xcode offers a complete set of tools for developing software, including a project manager, code editors, visual editors for your UI, debugging tools, simulators for different devices, tools for assessing performance, and much more. Xcode also includes a complete set of system code modules — called frameworks — for developing your software.
Download Xcode from the App Store
Xcode includes the SDKs for iOS, iPadOS, macOS, tvOS, and watchOS.
To create a new project in Xcode, choose File > New > Project and follow the prompts to create a tvOS app. New projects contain some default code to help you get started, with the type of app you select determining the development path you’ll take. For example, select TVML app if your app downloads its UI from your company’s server. For information about how to use Xcode, view Xcode documentation.
Adopt Swift
As you set up your project, consider which programming language to use. Swift is the preferred option because its syntax is concise, safe by design, and has modern features that make your code more expressive. Swift code also produces software that runs lightning-fast, and it’s interoperable with Objective-C so you can include source files for both languages in the same project.
Swift Programming Language Guide
The Swift Programming Language book gives a complete overview of the Swift programming language, and is the perfect place to begin your journey learning Swift.
Choose your app-builder technology
Another early choice to make is which app-builder technologies to use for your core infrastructure. App-builder technologies provide the foundational code you use to assemble your interface, handle events, and interact with the system. Each app-builder technology supports at least one development path, and some support multiple paths.
Choose from the following app-builder technologies:
SwiftUI
SwiftUI is the preferred app-builder technology, because it offers a modern, platform-agnostic approach to building your UI and app infrastructure. With SwiftUI, you specify your interface programmatically and let the system display and update that interface dynamically, including inside the Xcode editor. For a guided walkthrough of using SwiftUI, view the Introducing SwiftUI tutorial.
TVML and TVMLKit
TVML and TVMLKit offer a client-server model for building your app’s UI. Use TV Markup Language (TVML) to define your UI as a set of XML template pages. Store those pages and the JavaScript code you use to create your UI on your server, and download them at runtime to your app. Use TVMLKit to render those pages onscreen, and use SwiftUI or UIKit to implement the rest of your app’s infrastructure. For an example of how to create a client-server app using TVML, TVMLKit, and UIKit, view Implementing a hybrid TV app with TVMLKit.
TVUIKit and UIKit
TVUIKit and UIKit offer a library of objects for building your app’s UI and infrastructure. Assemble the views you display onscreen, and the navigation between different sets of views, visually using storyboards or programmatically in your code. TVUIKit provides tvOS-specific views, and UIKit provides common views like buttons and labels and the rest of your app’s infrastructure. For more information, view Creating immersive experiences using a fullscreen layout.
SwiftUI is the preferred technology for building your app’s core infrastructure and UI. All apps use SwiftUI or UIKit in some capacity, but SwiftUI’s modern approach leads to more maintainable code. The use of SwiftUI also doesn’t preclude you from using UIKit code. You can easily mix SwiftUI views and UIKit views in the same view hierarchies.
SwiftUI and UIKit work seamlessly with Apple’s data management technologies to support the creation of your interfaces. Swift Standard Library and Foundation framework provide the fundamental types you need to build your app, such as arrays and dictionaries, strings, numbers, dates, and other common data value types. For any custom types you define, adopt Swift’s Codable support to persist those those types to disk. If your app manages larger amounts of structured data, consider using Core Data or CloudKit to manage and persist that data.
Design the user experience
An app that offers an engaging experience keeps people coming back. Create a UI that looks good, has an easy-to-understand layout, and emphasizes the right content throughout.
Human Interface Guidelines
Apple’s Human Interface Guidelines offer invaluable information on how to design your app’s interface, navigate content, and manage interactions on Apple TV. Make reading these guidelines a priority in your explorations of the tvOS ecosystem, and use the corresponding Apple Design Resources to dive into designing your app.
There are certain features and technologies that are essential for tvOS apps. When planning your initial UI, make sure you consider the following features:
Dark Mode
This system-wide setting lets someone choose between a light or dark interface for their Apple TV. Dark and light interface styles rely on different color palettes and image assets, which you manage with the help of asset catalogs. For other parts of your UI, use system APIs to determine when it’s time to change between light and dark content. For details, view Supporting Dark Mode in your interface.
Scenes
Scenes are a crucial part of the infrastructure you use to manage your app’s interface. A scene coordinates interactions between your UI and the rest of your app. Scenes also respond to notifications that affect your UI, such as transitions between foreground and background execution. Make sure you support scenes in all your apps. For information, view SwiftUI and UIKit.
Automatic layout
Rather than adjust the position of views manually to accommodate different TV sizes, aspect ratios, and resolutions, tell the system how to make those adjustments relative to the current safe areas. SwiftUI and TVML adopt automatic layout as part of their UI design approaches. To adopt automatic layout in UIKit views, add Auto Layout constraints to your interface.
Scalable images
Incorporate SF Symbols to make your app more adaptable to changes. The SF Symbols app offers a vast collection of configurable, vector-based images that adapt naturally to appearance and size changes. They also blend well with the San Francisco system font, resulting in a consistent look across Apple platforms. View Configuring and displaying symbol images in your UI.
Design your interface with focus-based navigation in mind. Most interactions with your app occur through the Apple TV remote. People use the directional buttons on the remote to change focus from one part of your UI to another. They then use the select button to act on the focused item, or the Menu button to navigate back to the previous screen. Make navigation as straightforward as possible, and minimize text input and other complex interactions.
Lockups are one way to simplify navigation, and promote consistency among similar items in your UI. A lockup is a group of related views that you combine into a single, selectable element. For example, a movie lockup might include the movie’s title, description, cast list, and poster image. When someone selects a movie, tvOS places focus on the entire lockup instead of on individual items. For more information, view Lockups.
Support high-quality media playback
Its position in the living room makes Apple TV the ideal location for media-centric apps. Apple’s audio and video technologies give you access to a wide range of media formats, and the tools you need to play them at the highest quality.
Play and manage media
AVKit provides everything you need to play and manage your app’s audio and video content. Display video using the standard system interface, which offers built-in transport controls and supports AirPlay, Picture in Picture (PiP), interstitial content, and more. For more fine-grained control over your content, use AVFoundation.
Play high-quality spatial audio
Create the ultimate music player using AVFAudio, which contains the audio-specific types from the AVFoundation framework. Take your audio into another dimension using PHASE, which supports the creation of complex, dynamic spatial audio experiences in your games and apps.
Stream live or recorded content
Learn how to create streamed content and deploy it to your server using HTTP Live Streaming. Play back that streamed content from you app using AVFoundation.
Adopt best practices during development
Offer the best possible experience for everyone by doing the following:
Protect people’s privacy
Privacy is important, so keep people informed about how you use their data. If you collect data, offer a privacy statement that explains how you use that information. When you use Apple technologies that operate on personal data, include usage descriptions for the system to display on first use. For more information, view Protecting the user’s privacy.
Secure the data you collect and store
If you do collect data, make sure you protect that data from malicious attacks. Store very sensitive data such as passwords, financial data, or personally identifiable information in the user’s encrypted Keychain. Use on-disk encryption or other Apple security technologies to store other personal data. Use Apple CryptoKit to encrypt data that you store locally or send outside your app.
Audit your accessibility support
Apple builds accessibility support right into its technologies, but screen readers and other accessibility features rely on information your app provides. SwiftUI and UIKit can describe each piece of your UI, but only you know how those pieces work together. Review accessibility labels and other descriptions to make sure they provide helpful information, and make sure focus-based navigation is simple and intuitive. For more information, view Accessibility.
Internationalize and localize your app
Expand your app to international markets by localizing it for other regions and languages. Prepare your app using the Foundation framework, which supports the formatting of strings, dates, times, currencies, and numbers for different languages and regions. Ensure your UI looks good for both left-to-right and right-to-left languages. Localize app resources and add them to your Xcode project. For information about the internationalization and localization process, view Localization.
Design for everyone
Consider social and cultural differences when developing content, and avoid images and terms that have negative or derogatory connotations for portions of your audience. For more information, view Inclusion.
Test and debug your app thoroughly
During the development cycle, debug problems as they arise using the built-in Xcode debugger. Build automated test suites using XCTest and run them during every build to validate new code works as expected. Use the continuous integration system of Xcode Cloud to automate builds, test cycles, and the distribution of your apps to your QA teams.
Optimize your app’s performance
Eliminate bottlenecks and other performance issues in your code using the Instruments app that comes with Xcode. Profile your running code, find memory leaks, analyze resource usage, and much more. For information about how to gather metrics using Instruments, view Improving your app’s performance.
Choose a business model for your app
Distribute your app worldwide using a variety of business models, including free, free with in-app purchases, pay-to-download, and more. Build your interface in a way that offers a cohesive experience and supports your chosen business model. For more information, view Choosing a business model.
How to take it further
Once you have your app up and running, look for additional ways to improve the experience. Little things can make a big difference, whether it’s adding a particular feature, or approaching your content in a different way. For example:
Simplify the login process for your app
Adopt the system sign-in interface to let people sign into your tvOS app using an iPhone or iPad associated with the same Apple ID. Get people to their content more quickly by adopting multi-user support, which simplifies the process of selecting an app-specific user profile.
Allow people to connect from their other devices
Let people interact with your tvOS app from their iPhone, iPad, or Apple Watch. Create a secure network connection between your app running on both devices using DeviceDiscoveryUI, and use that connection to exchange data. For example, you might let someone control your tvOS app using touch input from their iPhone.
Showcase content in the Top Shelf
The top row of apps on the Apple TV Home screen can display additional content in the banner area immediately above. Deliver that content to the system using a Top Shelf app extension, which is a separate executable you include in your app. Use your extension to highlight new or featured content, or display someone’s favorite shows. For information about how to create this extension, view TV Services.
Allow people to share activities using SharePlay
SharePlay invites people to share your app’s activities over a FaceTime call. Use it to implement movie-watching night in your streaming video app, or use it to turn game night into a spectator sport. Define the activities you want to share using Group Activities. Synchronize media playback using AVFoundation.
Capture live audio and video for broadcast
Another way to share content is to capture live video and audio and save it as a recording or broadcast it live. Add this support to games or other apps when people might want to share their experience over email, messages, or social media. For more information, view ReplayKit.
Add runtime condition checks around new features
When you update your app to support a new version of tvOS, place runtime condition checks around code for new features. Runtime checks eliminate the need to ship different versions of your app: one for people running the new version of tvOS, and one for people running older versions. Everyone runs the same app, and people on the newer version of tvOS gain access to the new features you added. For information about how to add runtime checks, view Running code on a specific platform or OS version.
Make it easy for people to interact with your app’s content in other ways:
Make it easier to find relevant content
Think about how people use your app, and find ways to surface important content quickly. Use date and time information to highlight new or current content. Use machine learning to analyze data and offer better solutions. Rearrange your interface dynamically to make frequently used content more accessible.
Support universal links for your app’s content
If your website and app offer similar content, add universal link support to your app. With universal links, you don’t need to create separate URLs to open content in your app. One URL opens your app when it’s installed or your website when it isn’t. For more information, view Allowing apps and websites to link to your content.
Explore more
Learn more about technologies that provide unique capabilities, yet integrate tightly with Apple platforms to form a seamless ecosystem for apps and games across iOS, iPadOS, macOS, tvOS, visionOS, and watchOS.