Welcome to part 6 of my “Making Apple TV Apps” series. Today, we’ll be discussing the Apple TV’s “top shelf” area and how to populate it with dynamic content.
On Top of the World Screen
“Top shelf” refers to the top portion of the home screen display. It occupies approximately seventy percent of the screen when one of the apps on the top row is selected, as seen in the accompanying image.
Your app will have the opportunity to populate the top shelf whenever it is the focused on-screen item if the user has placed your app in the top row of app icons. Only apps in the top row can dictate what appears in the top shelf.
Assigning a static image to the top shelf is easy enough that anyone can do it. In fact, everyone has to do it, as every app is required to provide one. Apple added a new “Top Shelf Image” type to asset catalogs for this purpose, much like the existing “Launch Image” type.
Keepin’ the Shelf Fresh
Populating the content dynamically is a bit more involved, but not terribly so. To implement dynamic content, we take advantage of the TVServices framework. It is one of the three new frameworks that Apple added to tvOS. I described all three of them in part 3 of this series.
First, we add a new TV Service App Extension target to our project. We create the new target by selecting File, New, Target from the Xcode application menu, then selecting the tvOS – Application Extension, TV Services Extension options in the template chooser. The resulting additions will include a ServiceProvider source file that implements the TVTopShelfProvider protocol. This protocol contains two required read-only variables called topShelfItems and topShelfStyle.
protocol TVTopShelfProvider {
var topShelfItems: [TVContentItem] { get }
var topShelfStyle: TVTopShelfContentStyle { get }
}
The topShelfStyle property is expected to return a TVTopShelfContentStyle enumeration value. As of the time I’m writing this article, that enumeration contains two possible values: Inset and Sectioned. The Inset value indicates that you will provide a single flat list of items that the Apple TV should automatically cycle through. The Sectioned value means that you will provide a list that represent sections, with each section specifying its own title and one or more child content items.
Next, the topShelfItems property returns an array of TVContentItem items that are organized as a flat list if you specified the Inset style, or a list of grouped items if you specified the Sectioned style.
How you retrieve and collate the content to be presented in the top shelf is up to you. It could be locally-stored information in the key-value store, a response from a web service, or anything else imaginable within the realm of what can be accessed when the app extension is being executed.
Roll the Credits
Are you ready to add your own dynamic top shelf content to your tvOS app? I hope my guide was helpful. Next time, we’ll take a deep dive into the focus engine. I hope you’ll visit again for that, or sign up for it to be sent directly to your inbox.
Leave a Reply