tvOS build considerations

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.

Pre-requisitos

To develop for tvOS, you need the following:

• A fourth-generation Apple TV device (you also need a USB C to USB 3.0 cable, which doesn’t come with the consumer package).
• Xcode 7.1 o posterior.
• Set up provisioning for this device in the same way as for iOS devices. To test that provisioning works correctly, create an empty tvOS app with Xcode.

Setup notes

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.

Implementando input

There are two main inputs for tvOS:

• The Apple TV Remote (mandatory input)
• Made For iOS (MFi) controllers (optional)

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.

Estos son algunos detalles técnicos sobre el acceso a las características específicas de TV Remote:

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).

Setting up app navigation from the Unity UI

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:

1. Open the Input window in the Unity Editor. Find the first occurrence of the Submit virtual input, expand it, and change its Alt Positive Button to joystick button 14.
2. Select the EventSystem appObject in your Scene. In the Inspector, find the EventSystem component, and set a reference to the UI appObject that should receive initial focus in the First Selected property. You might need to enable the Force input module property in the Standalone Input Module component.

Note: Apple TV Remote navigation doesn’t work while your app is running in the TV Simulator.

Adding leaderboard resources to your Xcode project

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:

1. Open your XCode project.
2. Select Images.xcassets.
3. Right-click under the listed files, and select Game Center > New AppleTV Leaderboard from the menu that appears.
4. Add your images.
5. Select Leaderboard, then select Edit View in the right-hand pane.
6. Enter your leaderboard ID in the Identifier field.

Tip: If your asset compilation fails after making this chnage, try disabling the On Demand Resources option in the in Xcode build settings.

Implementing support for On Demand Resources

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.

Limitaciones conocidas

• The on-screen keyboard is limited to single line entries.
• tvOS Simulator doesn’t emulate the Apple TV Remote as an app controller, which means apps can’t access its input.