tvOS Top Shelf Tutorial: Static and Interactive
In this tvOS Top Shelf tutorial, you’ll learn how to add static and interactive content to the top shelf and give your tvOS app an edge over other apps! By Kelvin Lau.
A true Apple TV enthusiast can be identified by the plethora of installed apps on their Apple TV. But among the numerous apps installed to your user’s Apple TV are five apps that hold an elevated standing. The user explicitly chooses these apps to reside in a place of privilege on their Apple TV screen: the top shelf.
This space gives you, the developer, an opportunity to showcase what your app’s all about. Think of the top shelf as a billboard to show exceptional content from your app. When one of the top shelf apps in the top row gains focus, the entire top half of your user’s TV populates with one or more banners to charm your users:
A good top shelf is visually appetizing, while a great top shelf is visually appetizing and functionally appealing. In this tutorial, you’ll learn how to master the top shelf, and give your future tvOS blockbuster app a decisive edge over other apps in the marketplace!
Getting Started
Start by downloading the starter project for this tutorial. Build and run your app, and you’ll see the following:
Imagine it’s the year 2340, and that the Apple TV and Swift are so popular they’re still in use despite over 300 years of technological advancement. The project in this tutorial is a news app that showcases the latest news in the galaxy. Like other news apps, there are a variety of topics sectioned into their own tabs. At launch, the app shows the user the top news from every category, and subsequent tabs showcase all the news attributed with the topic:
Press Command+Shift+H to bring your tvOS simulator back to the home page. You’ll begin by putting your news app into your top row of apps to expose it in the top shelf.
Bring up the tvOS simulator controller by pressing Command+Shift+R. Navigate to your news app by holding the Option key in your keyboard while making swipe motions with your mouse indicator on top of the tvOS simulator controller.
Once you’ve brought the focus to your news app, click and hold on the touch area until the app icon starts wiggling. Bring the app to the highest row of apps and tap on the tvOS controller. Your app should now reveal its top shelf when you bring it in focus. Right now, it will appear as a blank canvas:
That wouldn’t win over any galactic news fans, in any universe! A good logo and good branding go a long way; in the case of the Apple TV, that extends beyond the app icon. In fact, Apple enforces this: you must provide a top shelf image before you can export your app to production servers.
Adding a Static Image
Later in this tutorial, you’ll learn how to create an interactive top shelf, but it’s baby steps for now. You’ll start by implementing the minimum acceptable top shelf: a high quality 1920 x 720 .png image relevant to your app.
Open the resources folder from this tutorial’s resources and locate StaticTopShelf.png. Drag and drop this image into your Assets.xcassets folder in the Top Shelf Image compartment. For simplicity, you’ll just add the @1x image resolution:
Ensure your app is still within the top row of apps, then build and run your project. Press Command+Shift+H to return to the home screen, then navigate to your app and you should see your top shelf image in all its glory:
Right now, your top shelf consists of a single banner that acts as a symbol for your app. While that’s great and all, the usability of the top shelf extends far beyond being a “second app icon”. In the following section, you’ll learn how to develop for the interactive top shelf.
An Interactive Top Shelf
There are currently two different interactive top shelf layouts: the sectioned top shelf, and the inset top shelf.
Sectioned Top Shelf
The sectioned top shelf is, as its name implies, a top shelf where the content is divided into sections. If you’ve worked with table and collection views before, this layout should look familiar to you:
The sectioned top shelf is perfect for displaying information that makes sense when it’s grouped together; this makes it a great choice to showcase the top news articles for each news topic. In general, if the purpose of your app is to feed information to the user as quickly as possible, the sectioned layout is a great choice.
Inset Top Shelf
The inset top shelf is great for displaying the overarching themes of your app, particularly if your app is a game. Each item is given the full width of the screen to showcase the features in store for your users.
Both layouts let the user scroll and browse through the your content — and they’re surprisingly easy to implement.
Setting Up the Interactive Top Shelf
The process of setting up an interactive top shelf is relatively straightforward. In technical terms, you’ll add a target — a TV Services Extension — and configure the ServiceProvider to use one of the two layouts.
On the top bar, select File\New\Target…:
For the template, choose TV Services Extension located within the tvOS section and select Next:
Name the extension TopShelf and select Finish:
At this point, you may be presented with the following dialog:
Select Activate. If you didn’t get that dialog you may activate the scheme manually by clicking on NewsApp in the schemes list and selecting TopShelf. This lets the simulator test your extension. With that bit of setup done, you’re ready to begin writing code. Hurrah!
TVTopShelfProvider
When you create the new TV Services Extension target, Xcode automatically generates the new target accompanied by a new file named ServiceProvider.swift. This file contains the ServiceProvider class, which is where you’ll define the interface for your interactive top shelf.
The topShelfStyle computed variable defines the type of top shelf you’d like to present to the user: either the sectioned layout, or the inset layout. In this tutorial, you’ll use the sectioned layout.