Apple TV (tvOS)

The Apple SDK runs on tvOS 18 and later. You install and initialize it the same way as on iOS. See Install and set up the Apple SDK. This page covers what is different on tvOS.

For OTT support across Apple TV, Android TV, and Fire OS, see OTT platform support.

What works on tvOS

These features work on tvOS:

• Scenes, shown as modals or banners.
• Embedded content. Add an AirshipEmbeddedView to your SwiftUI screens the same way as on iOS. See Embedded Content.
• Message Center, for messages that use Scene content.

For every feature and its tvOS limits, see Platform support.

These do not work on tvOS:

• HTML Message Center messages. tvOS has no web view, so a message with HTML or plain content shows “This message can’t be shown on this device.” iOS SDK 21.1+ Use Scene content for Message Center messages that target tvOS.
• Web view elements in Scenes, and YouTube and Vimeo media.
• Live Activities.

Remote navigation

People use a Siri Remote or Apple TV Remote to move through a Scene. Navigation is based on focus. The control with focus is highlighted, and the select button presses it.

Focus

Buttons and form inputs in a Scene take focus. Swipe on the remote or press its directional buttons to move focus between them.

• When controls overlap in a container, a directional move goes to the nearest overlapping control in that direction. For example, a close button drawn over a full-size button can take focus. iOS SDK 21.1+
• A button with no tap effect still shows focus. The tap effect only controls the press animation. iOS SDK 21.1+

Dismiss with Back

Back closes a Scene modal. iOS SDK 21.1+ On older remotes, this is the Menu button. The SDK handles the press, so Back does not send the person to the Apple TV Home screen while a modal is showing.

Back always closes a modal on tvOS. You cannot turn it off for a Scene. Because a close button might be hard to reach with a remote, Back is the reliable way out of a modal.

Push notifications

Push on tvOS uses APNs and is set up the same way as on iOS. See Get started with Push Notifications on Apple. Add the Push Notifications capability and the Remote notifications background mode to your tvOS target.

Visible notifications

tvOS does not show alerts or play sounds for notifications. Visible notifications are limited to the app icon badge. On tvOS, the SDK requests badge authorization by default, and badge is the only authorized setting it reads. For more about badges, see Badge Management.

A channel on tvOS is opted in to push when all of these are true:

• The app has an APNs device token and is registered for remote notifications.
• Airship.push.userPushNotificationsEnabled is true.
• Badge authorization is granted.
• The push feature is enabled in the Privacy Manager.

Background push

Background push registration is separate from opt-in. The SDK registers for remote notifications when the push feature is enabled, whether or not userPushNotificationsEnabled is true. It reports background push as its own channel setting. A channel can accept background pushes while it is opted out of visible notifications.

For background push to work, you need the Remote notifications background mode in your app and Airship.push.backgroundPushNotificationsEnabled set to true, which is the default.

Message Center inbox

The Message Center inbox syncs over HTTP. The SDK refreshes the inbox when Message Center opens and when your app becomes active. It does not need push, an APNs token, or push opt-in. It needs the Message Center feature enabled in the Privacy Manager.

A push that carries a Message Center message ID also makes the SDK refresh the inbox, so new messages can appear before the person opens Message Center. This needs background push.

For setup, see Get started with Message Center on Apple. On tvOS, the message list has no select, delete, or bulk mark-as-read controls.

Simulator limits

The tvOS Simulator does not get an APNs device token. The SDK counts a channel as opted in only when it has a token, so a channel created in the simulator stays opted out of push. To test push, run your app on an Apple TV.

Scenes, embedded content, and the Message Center inbox do not depend on a token. By default, the SDK uses your development app credentials in the simulator. To see why a channel is not opted in, check Airship.push.notificationStatus. See Troubleshooting Push Notifications.