The Top Shelf

Hi, everyone. My name is Rachel Roth and I'm a User Experience Evangelist at Apple in Cupertino.

We have one last thing to talk about when it comes to app development and that's how to make the most out of the Top Shelf.

The Top Shelf is the area above the top row of app icons on the Apple TV home screen. And when someone puts your app icon in this top row and brings it into focus, you get to control what displays here. So, what you're seeing here is the top shelf content for iTunes Movies. Now, this area is a very high engagement area, so it's a great opportunity to showcase content to people who are already fans of your app or your game. Now, it's not meant for marketing to new audience members.

If someone has moved your app icon into the top row, then it's highly likely that they are already regularly using your app or playing your game. So, you want to use this space for showcasing meaningful content to those people.

Now, everyone must include a static image as part of the app bundle. And as the name implies, these images are not interactive, it's just one big image. So, you want to use the static image to reinforce branding and generally start immersing people into the world of your game. The static image for Alto's Adventure is a great glimpse into the world of snowy llama chasing.

And Badland's static image gives you a taste of their highly stylized artwork. Now, it's very important that the static image does not look interactive because it isn't. So something like this, say a screenshot of the starting screen of a game, would be very confusing. It looks like you can swipe up and click those buttons but it's a static image, so this is just going to frustrate people. So instead, create something that's a visually rich reminder of the characters from your game, the world that people are going to enter into. And the static image is only going to be updated with the app bundle, so make sure that this is timeless content that doesn't require frequent updates. Now while everyone has to include a static image, you also have the option of providing dynamic content. Now, a lot of the people told me that they plan to implement this later because it seems like a nice to have feature. But this is a huge opportunity to get new content in front of people.

And it's very high engagement, so you really should take advantage of it. All of the elements in dynamic content are focusable, so people can click on something in the top shelf and immediately start watching a movie or competing in a game tournament or exploring destinations for a vacation without having to launch your app or game and browse through various menus. And dynamic content is loaded from your server, so you don't need to update your bundle to refresh it. So this means that content will always be current. Now, you have a choice of two styles of dynamic content, either inset banners or a section content row. Sing by Smule uses inset banners and they're using their Top Shelf content to showcase artists you can sing with. Now as you can see here, these banners rotate automatically but you can also swipe up and go through them at your own pace.

Now since they're focusable, you can provide layered images to take advantage of the parallax effect but flat images are also fine.

Inset banners are kind of like billboards. They should be self-explanatory. They're entirely self-contained.

There's not going to be a secondary label underneath when they're in focus, so you want to include any type that you need as part of the treatment.

And I happen to really like this one. I think the image of Jessie J is really engaging and there's a fun type treatment that's letting me know what I can do, sing along with Jessie J. And the inset banners are always rectangles You're not going to have to copy down any of these numbers because all of them are documented in the Human Interface Guidelines for you. Now Zova Fitness uses the sectioned content row for their top shelf. Like the inset banners, all of this content is focusable and you can use either layered or flat images.

The content row holds still until the people interact with it. So you want to make sure those first few things are going to be the most relevant to someone. Now, the content row items get an additional label underneath when they're in focus, and you get to provide a heading.

And this heading is great for giving people context. So this helps us know that we are looking at workouts that were chosen by Zova's editors.

You have a choice of several aspect ratios for content in the content row and I'll take you through the most common ones.

Zova uses square artwork. iTunes Movies shows all the top movies using poster sized artwork.

And Artsy is using 16 by 9 artwork to showcase the imagery from their featured art shows. But you don't have to pick just one, you can mix and match different aspect ratios just like Newsy has done here. OK, so which one should you choose? If you have a lot of things, the content row has been optimized for higher volumes. But if you just have a few things that you really want to highlight in more detail with that visually rich billboard style graphics, then you want to use the inset banners.

Now in both cases, anything in the top shelf acts as a shortcut to that content deep inside of your app. Zova's top shelf content lets you jump right into the details of a featured workout instead of clicking through several views in the UI. So I can find a workout that I'm interested in and then click for more information. And I bypass that main screen automatically. You can also specify a different destination if people use the play/pause button. So in this case, if I press play/pause on one of these items-- Next up, jump rope.

That gets me right into playback of the workout program, bypassing several views entirely. So if I'm inspired to workout, there's nothing that's going to come between me and the program. And you can show multiple types of content in the same row by separating them with different headings like Newsy's does. First, they show you what's live and then this is followed by other top stories.

And selecting any of this jumps you directly into their new story. And when I'm done watching this story, I remain inside of the Newsy app, where I can keep browsing for other things to watch. So, you can see how this is an incredibly effective way to get people to reengage with your app. But dynamic content becomes even more powerful when you personalize it.

It's highly likely that I'm going to want to watch a movie that I recently purchased. So, iTunes Movies places that at the beginning of the content row. And that's a very handy shortcut. It saves me from launching the app, navigating my way to the purchased tab and then finding the movie again. But at the same time, I can still browse other top movies. So, as you can see, dynamic content in the top shelf is a great way to reengage people who are excited about your app, so I highly encourage you to take advantage of it.

And integrating dynamic content is pretty straightforward, so I'm going to handed it off to Stefan to give you some tips. OK. So, the way you can provide the dynamic content for the top shelf is through an extension. And it's-- this is a TV services extension. And this will be a part of your tvOS app.

We're using the same mechanism that you might already know from looking iOS extensions or watchOS extensions but this is a specific extension for this platform.

And this extension provides a collection of metadata items to the system, to render the top shelf for your app. Now as you have just seen, top shelf supports the user, moving focus into the top shelf, and then selecting one of the metadata items which will take them directly into the specific view inside your app.

And also, the system will load the top shelf content dynamically from your server, so that you can change it any time without having to update the app.

To create the TV services extension, you just create a new target in your Xcode project and then you use the TV Services Extension template.

And this will create a new class, the principle class for this TV Services Extension that has to provide and implement a very simple protocol, which is the TVTopShelfProvider protocol. And all you need to do is you basically just provide the content for those two properties and thereby implementing this protocol. The first one is the topShelfStyle and the second one is topShelfItems.

Let's take a look at these two properties. Now, let's start with the style. And style is defined with one of two options, either inset or sectioned, and this is what Rachel was just talking about. This corresponds to the-- either the inset banner style or the sectioned content row.

The other property you have to provide is the TVContentItem array. And that's part of the actual metadata that you want to provide for the top shelf. Now for that, you use a class TVContentItem that is a simple model object that we provide for you, so that you can use that to store the necessary metadata for the top shelf. And this has a variety of properties that you can use to specify this metadata. The first one is the contentIdentifier, which you can use to identify the item in your app, so that your app knows exactly what it represents. Then you should use a title, descriptive title that will be displayed in the section content row.

And then of course, you also want to provide an imageURL that points to the web resource that provides the image for this top shelf item.

With the image goes the imageShape property and this is a constant that you have to define that specifies the aspect ratio.

There are some other properties that we also provide that you can also use which are currently not used in the top shelf but it's very likely that you might want to use the TV content item in some other places in your app as well. And so, there's an opportunity for you to store things like duration, playback position, and things like that in those objects as well. Now for the section content row, you also need the topShelfItems property and I'll talk a little bit more about how that works in a bit. OK. Now, let's say you want to provide this extension and you want to provide the content. So, if you use the inset banner style, it's very simple. So basically, you just pick the inset style and then your TV content items array just provides a simple array of the items that you want to have being displayed in the top shelf, one for each banner.

So if you have, let's say four items that you want to display there, you will have an array with four objects, with four TV content items that correspond to the banner.

So you can see, pretty simple. Now for the sectioned content row, it's a little bit different.

You still provide an array of TV content items from the extension but this time, only one item for each of those sections. So, let's say you have two sections in your section content row, then you would provide an array with like two items that are basically just for the sections, and then you would specify the title for those sections which becomes the title that's visible in the top shelf. And the actual content and the actual metadata for the objects that are part of these sections will be stored in the topShelfItems property, which I was just talking about. And this is basically a hierarchy now that you create where you have, let's say for this first section, we have three content items that we want to actually display. So, you provide an array with three items for that section. And then for the other section which has, say five items, you provide a separate array and put that into the top shelf item property of the TV content item that represents this section.

This is how you provide the metadata. Now, Rachel was also talking about how you can link to content.

To make this work, the first thing you need to do is you need to register a custom URL scheme for your app. We're using the same technology that we've been using in iOS for years. And tvOS will use this custom URL scheme to launch your app with the information that you provide as part of the URL passed to your application delegate. Now, as part of the TV content item, you specify a display URL and this is the URL that's going to be used when somebody clicks your item in the top shelf by just clicking down or pressing down the touch surface on the remote.

But then you also specify a play URL which is the item or the URL that is going to be used if somebody presses the play/pause button on the remote.

And both of these URLs can be used to launch straight into a specific part of your app. If it's the -- Display URL, you should launch into something that corresponds to something like a details page. And if it's the play URL that's going to be used, then you probably want to launch straight into playback of a video. Or if it's a game, then you probably want to jump directly into game play.

A couple of tips and tricks. So, we recommend that you provide both the display and play URLs for shortcuts into your content at all times.

And also-- Usually, the system will keep the top shelf up-to-date and load data periodically. But if you want to tell the top shelf that the content needs to change while your app is running, you can just request an update from within your app by simply posting a TVTopShelfItems DidChangeNotification. The system will pick this up and then will reload the content for your top shelf.

And this is one of the things that you might be using when you want to personalize the content and if the user-- for example, the user switches in your app and you want to make sure that the top shelf provides the other user content now. But talking about personalizing the top shelf for specific use, another thing that you probably need to do is you want to share data between the extension that runs the top shelf and your app.

And to do that, you can use App Groups and you need to set up App Groups to share data between the app and the extension.

And the-- For more information about how that works in detail, have a look at the app extension programming. This is exactly the same process that it would be using on iOS as well. So with that, some more information again. We like to point you to our landing page on developer.apple.com. You're going to have a lot of information in the human interface guidelines, also how to design your top shelf. And the app programming guide for tvOS also has a whole section just about the top shelf. And I also want to point out that the UIKit Catalog sample app also provides an implementation for both styles of the top shelf. So if you want to see some code of how this is done, take a look at the sample project.