This manual page is primarily aimed at helping developers transition from iOS to tvOS. The Apple TV platform, also known as tvOS, builds on the foundation of the iOS platform, but also creates new challenges for app developers. You can easily deploy an existing iOS app on tvOS, but often you must adapt your app’s content to work with tvOS input controls and display correctly on a bigger screen.
To develop for tvOS, you need the following:
It’s best practice to create a separate branch or copy of your app and port that to Apple TV. Many iOS plug-ins aren’t compatible with Apple TV, because Apple TV only supports a subset of the iOS framework. Unity has no control over third-party plug-ins and their cross-platform compatibility.
If your app uses more than 4 GB on disk, break it into smaller parts and use On Demand Resources. To learn more, see the On Demand Resources section below.
Note: Bitcode is included with tvOS builds, which adds around 130 MB to your executables. App Store servers strip this code, so it doesn’t affect your distribution size. To estimate Bitcode size, analyze the LLVM sections in your executable from the command line with otool -l.
There are two main inputs for tvOS:
The Apple TV Remote (Siri Remote) is a multi-purpose input device that works as a traditional menu navigation controller, app controller, gyroscope, acceleration sensor, and as a touch gesture device. Unity routes Apple TV Remote input to corresponding Unity APIs, but performs no other processing on that input.
Your app might need some adjustments to its input scheme to leverage the Apple TV Remote’s specific input features. For instance, your app can treat it as a traditional app controller, with one analog axis and an extra action button, or your app can use the accelerometer for interactions such as steering. You can experiment with various schemes when porting an app to tvOS.
Unity offers Made For iOS (MFi), which is standardized controller support for iOS and tvOS. MFi controllers offer out of the box input mappings, and you can set up custom action mappings in the Unity Editor (menu: Edit > Project Settings…, then select the Input category). For more information, see documentation on iOS Game Controller support, and Apple developer documentation on Game Controllers.
Two further wireless Made For iOS (MFi) app controllers can be connected to an Apple TV device, which effectively turns it into a console. Your app can use the controllers in the same way as iOS MFi controllers, but you must ensure its usability with the Apple TV Remote alone. The tvOS system limits the number of additional controllers to two.
Here are some technical details on accessing specific TV Remote features:
| Apple TV Remote button or function | Notes |
|---|---|
| Touch area | Maps to both Input.touches (Touch.type is set to Indirect and is ignored by the Unity GUI), and the Joystick Input API (for example, Input.GetAxis("Horizontal"); ). |
| Touch area click | Maps to button A, which then maps to joystick button 14. |
| Gyroscope | Maps to Input.gyro. Input.gyro.attitude derives from the gravity vector, and as such it doesn’t rotate around the axis parallel to the gravity vector. The same applies for Input.gyro.rotationRate. |
| Acceleration | Maps to Input.acceleration. Note: Input.acceleration derives from the gyroscope API and might have some instabilities. The tvOS SDK doesn’t have a dedicated accelerometer API. |
| Pause/Play button | Maps to button X, which then maps to joystick button 15. |
| Menu button | A long press calls the tvOS task switcher. You can’t override this behavior. Your app can process short taps one of two ways: a) Return to the tvOS system home screen, if UnityEngine.tvOS.Remote.allowExitToHome is true.b) Let your app respond to taps (which maps to the Pause button/joystick button 0) when UnityEngine.tvOS.Remote.allowExitToHome is false. This the default behavior.Your app should switch between a) and b) based on its current state: - If the user is currently interacting with the top menu, enable behavior a). - If they’re interacting with the app in real time, enable behavior b) and call the in-app pause menu when they press this button. |
| Swipe to the edge of the remote | Generates directional pad (D-pad) up/down/left/right button presses. For a list of mappings, see documentation on iOS Game Controller support. |
You can control the Apple TV Remote operational modes via a dedicated API as follows:
* UnityEngine.tvOS.Remote.allowExitToHome
* UnityEngine.tvOS.Remote.allowRemoteRotation
* UnityEngine.tvOS.Remote.reportAbsoluteDpadValues
* UnityEngine.tvOS.Remote.touchesEnabled
Note: When UnityEngine.Apple.TV.Remote.allowExitToHome is false, the Menu button maps to joystick button 0. This causes a conflict with the default Input window, because it also uses joystick button 0 to map the Submit virtual button. This results in the Menu button triggering actions on UI elements. To fix this issue, remove or modify the Submit virtual button bindings in the Input window (menu: Edit > Project Settings, then select the Input category).
You must provide custom visual resources to the Apple Game Center for its native leaderboard UI. Here’s how to set them up in Xcode:
Note: Apple TV Remote navigation doesn’t work while your app is running in the TV Simulator.
The Apple Game Center requires you to provide custom visual resources for its native leaderboard UI. Here’s how to set them up in Xcode:
Tip: If your asset compilation fails after making this chnage, try disabling the On Demand Resources option in the in Xcode build settings.
tvOS limits how much disk space your application can reserve. The main application installation bundle size can’t be larger than 4 GB. The limits for additional downloadable content are up to 2GB for in-use assets, and up to 20GB of total downloadable content. Apple recommends On Demand Resources (ODR) for tvOS downloadable content, which is the best disk space management for tvOS. Unity supports ODR via Asset Bundles. For more information about ODR implementation, see the Unity blog Mastering on-demand resources for Apple platforms.