Apple TV App and Universal Search Video Integration - Part 1

George Karas: Hello, my name is George Karas, and I am part of Apple's Video Partner Operations team.

In this video we'll be covering two topics.

First, a product overview of the Apple TV app and universal search features.

And second, a deep dive on how to integrate content from your video service with these services via metadata feeds.

So let's get started with an understanding of what these features are in better detail.

First, universal search, which can be experienced by customers in two primary ways: with Siri via your voice to search for content you want to watch, as well as text-based search through Spotlight on iOS and macOS.

Safari on macOS is also supported.

The supported content-types within universal search are movies, episodic TV series, and live sporting events.

Apple then displays content in a universal fashion on our canonical product pages.

Now, let's talk about the Apple TV app and understand how this compliments universal search.

The Apple TV app is a standalone application that is preinstalled on both iOS and tvOS devices in over 100 countries, and is a place for everything a customer wants to watch, all in one place.

The Apple TV app brings everything together: movies, TV shows, sports, and news.

It also tracks playback as a person watches content across their favorite video services, so that they can resume watching right from the TV app, across all of their devices.

The Apple TV app also provides notifications to customers when a new episode is available of a TV series, their favorite sports team is playing live, or there's a close game that Apple thinks you wouldn't want to miss.

In addition to these features, Apple's Editorial team curates content in a variety of ways to promote new things to watch, allowing customers to discover new programs from your service.

Next up is the Siri Live Tune-In feature, which is available on both iOS and tvOS and allows customers to tune directly to live channels with their voice via Siri.

For TV providers who are bringing their full suite of channels to Apple's platforms, this is a great way to allow your customers to conveniently navigate your entire EPG by their voice simply by requesting the name of the channel that is desired.

Now that we've covered what these features are, it's time to understand how to technically integrate with them.

In order for your service to integrate with these features, metadata feeds are required to be provided to Apple so that your content can be displayed within the Apple TV app.

These metadata feeds are provided in Apple's XML specification, and there are two kinds of feeds you will need to understand and develop to participate with this service.

First, the catalog feed, which contains descriptive metadata about your VOD movies and TV shows and live sporting events.

If you are integrating live sports into the Apple TV app as well, then Apple recommends you provide two separate catalog feeds: one for your VOD content items and another for your live sports.

The second type of feed is availability, which corresponds to the catalog feeds provided separately, and informs Apple when your content is playable with start and end dates along with deep-link URLs that the Apple TV app will use to direct customers to your application, so content can be opened and played.

Let's first start with an overview of the catalog feed.

Again, this is an Apple XML feed of descriptive metadata, such as titles and descriptions.

TV series are structured appropriately across three different content types: TV shows, TV seasons associated to the show, and TV episodes that make up the season.

Apple also supports season lists and mini-series TV-show types that can be provided without the TV season level, and instead only the show and episodes.

In addition to these elements, we request that you provide a release date for movies, premiere dates for TV shows, and air dates for episodes.

Ratings or age classifications can also be included in your catalog feed, along with cast and crew information and the network that originally aired the TV show or studio that produced the movie.

All of this information from your catalog feed is used for mapping purposes on the Apple side, so that we can accurately understand that your content matches existing references for the same movie or TV show in our system and can present it accordingly on our canonical product pages.

The last key piece to the catalog feed is artwork, which can be provided for your movies and TV shows.

Apple has the ability to leverage existing metadata and imagery to build out the canonical product pages.

However, it is important that your metadata meet our quality standards, so that it can be managed efficiently by Apple.

Artwork is important to be sure your content is displayed well within the Apple TV app, especially for content being prominently placed or promoted by Apple's Editorial team.

Now let's take a look at some XML samples to get a bit more familiar with these feeds.

Here we have a sample for providing a movie in the Apple XML catalog feed specification.

The first things that call out is the contentType element -- which in this example, is equal to movie -- and a contentID that you'll use to identify an item in the feed.

It's important that the contentID values you provide across your items are unique to meet the spec and also remain static for that item.

Now let's take a look at how some of the descriptive metadata elements are provided.

Here we can see the following: title, description, genre, ratings, and credit information.

It's also important to notice how certain elements, like titles and descriptions, are provided with a locale that indicates the language of the metadata.

Locales are very important for processing your metadata in Apple systems and displaying it correctly on our customers' devices.

In addition to the metadata you are able to provide for your content from your own systems, you are also able to provide an external identifier, such as a TMS ID from Gracenote that can help Apple with mapping your content efficiently.

This is especially important if you have challenges around providing certain pieces of information accurately to the definitions of Apple's specifications.

Within the movie item, cover artwork can be provided, and it's important to note that in addition to the cover artwork shown in this example, there are a variety of supported image types that can provided for your content through the feed, such as background images and title-treatment logos.

You'll need to study the documentation available for further detail on images.

Lastly, within the movieInfo block is where you will provide other factual information, such as the type of the movie, the duration in seconds, production studio, and the original release date.

All of these are very important for mapping on the Apple side.

Now, for quick comparison, let's look at a TV-show example, which is very similar to a movie but with some important differences.

The contentType element is used to distinguish this item correctly as a TV show, and the same rules apply for contentID values here, as mentioned for movies.

Similar to movies, we have a set of descriptive information: title, description, genre, ratings and advisories, and credit information.

Locale values are equally important here as well.

Cover artwork and other image types can also be provided for TV shows by indicating the URL the image is available at, the type of image it is, and the locale to represent the language of the artwork if it contains text.

As mentioned, there are different types of TV shows, which will impact the structure of the TV episode that relate to the show: standard with seasons; seasonless or miniseries are without seasons; and then along with the network that originally aired the TV show; and the date it originally premiered, which can be worldwide or local to a country.

Now, let's talk about sharing information about your sporting events in the catalog feed.

Again, Apple encourages you to provide a separate catalog feed for your sporting events, different from your VOD catalog feed that contains your movies and TV shows.

For each item in this sports feed, you must indicate the type of sport it is -- such as basketball, baseball, or cricket -- and the league or tournament the event is a part of.

For both of these, Apple provides a dictionary of sport name and league abbreviation that are required to use in the catalog feed.

For mapping purposes, it is important to indicate the season of the league the event is a part of, as well as the competitors participating in that event, which would be the teams playing in the game or individual athletes, depending on the type of sport you are providing.

Additionally, including venue information helps our system with processing and mapping your sporting events.

And when it comes to artwork for sports in the Apple TV app, it is not required to be shared in the catalog feed.

Apple handles artwork for sporting events entirely from third parties that we manage and work with to ensure images are appropriate for use in the Apple TV app.

So let’s take a look at how sports look in the catalog feed.

Just like we saw before for movies and TV shows, you must indicate the contentType equal to "sporting_event" and provide an appropriate contentId value.

Titles and descriptions are supported in the same way, along with external identifiers to help with mapping if these are available to share.

Within the sportingEventInfo block is where you will indicate the sport name and league abbreviation.

Venue information has its own block so that you can indicate the name of the stadium along with where it's located.

For competitor's data, you will provide the name, such as Lakers and Warriors; team abbreviations from your own system, if available; and designation of each of these as the home or away team.

If you are unable to provide competitors for a particular event, the venue information will be required for that item.

Now that we have reviewed the catalog feeds at a high level, let’s talk about the availability feeds that you will also need to provide so that your content can appear at the right time in the Apple TV app.

There’s three types of availability feeds that are important for you to understand.

The first schema is VOD for your on demand movie and TV show content.

The second is a linear availability schema for your live sporting events that take place on a 24/7 linear channel.

It’s required to provide one linear availability per channel that carries live sporting events.

The last schema is similar to VOD, but is an availability feed for live sporting events that are played in event-based fashion on a video service.

This is to support live games, outside of a 24/7 linear channel, where the playable stream is only available on your service for duration the game is being played live.

First, let’s understand some basics before we dig into these types further.

Each availability feed you provide will require a serviceId value that must be unique, and used to identify the feed in Apple’s systems.

Each item in the availability feeds will need to also reference the catalogId value so that Apple can match up the information appropriately.

Playable properties allow you to indicate the audio language and video streaming quality of the content or channel you are providing the feed for, in addition to any advanced media options that may be available, such as HDR.

The primary purpose of the availability feeds is to control the availability and presentation of your content within the Apple TV app by offers -- window start and end dates -- and restrictions -- information about where and how your subscribers are able to play back the content.

So let’s dig in, starting with the VOD availability feed.

For each playable item, start and end dates are shared to control when your video service can be included as a playable option on the canonical product page.

Deep-link URLs are also provided for each item so that the Apple TV app can send customers to your application to open and play the content appropriately.

And additional restrictions are shared if your content requires the customer to have a specific subscription package.

Here’s a sample of a movie item provided in the VOD availability feed.

You can see here that the contentType for that item is also indicated in this feed, in addition to the contentId value and catalogId value that carries the rest of the descriptive information for it separately.

Via the locators elements, you are able to provide the appropriate deep-link URLs for your iOS and tvOS applications so that the content can be opened for browsing, or to initiate playback automatically if the customer has the appropriate entitlements to do so.

Playable property information is shared to indicate the language that the content is available in, the quality of the video stream -- which for this example is a movie playable with HDR capability.

Additional language components that may also be available -- like English closed captions or Spanish subtitles, as presented in this example -- can be indicated within the playable properties as well.

Within the offers element is where an offer can be provided to specifically identify the windowStart and windowEnd dates within it.

The offeringType indicates what type of customer can play the content.

In this example, we see the Subscription type shown, and the other two possible types here are Free and Account.

Subscription represents paid subscribers, Account represents customers with an association to a video service with something such as an email address, and Free indicates the content is readily playable for anyone without any sign-up or payment required.

The availability feed supports the concept of content changing offering types, and restrictions can also be added to the offeringType to represent various subscription packages that are a part of your video service.

For multiple offers, simply repeat the offer elements with their respective offeringType and window dates, and add restriction tier elements to package your content according to how it is offered to your customers.

The tier names used are for you to define but must represent packages, and it’s best to avoid special characters or exceedingly long values.

Now let’s review linear availability feeds, which are used to provide information about when live sporting events are playing on a specific channel that is part of your video service.

Start and end dates are provided, along with the stream properties of the channel, so that Apple can represent the audio language and video quality appropriately.

Just like VOD, deep-link URLs are shared within this feed.

However, these are specific to a playable linear channel in your video service instead of being specific to a content item.

Live and broadcast flags are important to represent the content accordingly to Apple, and present these games as live events or re-airs within the Apple TV app.

Here’s a sample linear availability feed to help you get familiar with the differences from VOD.

The basics apply here as well, as these also have their own serviceId used to identify that channel’s feed, along with a serviceType equal to "linear" to differentiate the data in Apple’s systems.

Because a linear availability feed is required per live channel, the serviceId must be unique across these feeds.

Locator deep-links are also provided at the service level of the feed, and here we can see playableProperties information being used to indicate this is an English-language channel with closed captioning, HD video quality, and 5.1 surround sound capability.

And serviceOffers are used to represent that this channel is available to subscription-level customers, but additionally restricted to those that also subscribe to sportsPackage12, and are in a specific location of the United States as represented by the Nielsen DMA value indicated.

To help you develop these feeds, here are some things you should know.

XSD files are available with the specifications to assist with your validation exercises.

Apple also provides access to the Media Feed Validator tool to generate validation reports and a visual representation of them to be sure you are meeting Apple’s specifications and quality standards.

Once your feeds are passing the Media Feed Validator without errors, they are ready for review by Apple.

All feeds are reviewed by Apple before being accepted into our production system for regular ingestion, and upon approval you can start testing your video service integration with the Apple TV app.

Thanks for joining this session to better understand the product features of the Apple TV app and the metadata requirements to participate with the service.

Adhering to the specifications and recommendations in this video will help make your onboarding process a smooth journey towards customers enjoying your best video content from the Apple TV app.

Thank you!