Prepare Content

Set up offers and tiered content

In order for content to go live on the Apple TV app, the content item must have a valid and current offer associated with it. Offers are supplied in the availability feeds and should have a corresponding catalog item. See the UMC Availability Data Interface Specifications for full details on how to implement offers.

Depending on the service type, there are different offers that may apply to your availability feed:

VOD offers <offer>: Used to describe the type of offering (for example, free or subscription) along with the offering time window and restrictions for content offered in a VOD service. VOD offers should only be applied to TV episode and movie content types.
Linear offers <linearOffer>: Used to describe the offering time window and restrictions for live content offered in a linear service.
Service offers <serviceOffers>: Used to describe the type of offering (for example, free or subscription) along with the offering time window and restrictions for a linear service. This will apply to the entire service.

There are several types of offers that impact how viewers access content:

free should be used for items that can be accessed by all users, with no account or subscription necessary.
account should be used for items that are free but require an account to access (Video App Integrations only).
subscription should be used for items that require a subscription to the service to access.
coming_soon is used for items that will be available in the future but can be discoverable in advance of release.

At this time, coming_soon offers are only for Apple Subscription Video VOD content when approved by Apple, and only apply to TV shows and movies. Outside of this specific use case, TV shows should not have any other offer types except for coming_soon, since TV episode offers will override overall TV show availability.

While you cannot apply more than one of the same offering type to a single content item, you can apply different offering types to one item. For example, if you would like to make an item available for all users for a short window of time, you can apply a free offer to an item that has an existing subscription offer.

<item contentType="tv_episode" contentId="EPI10054611" catalogId="com.catalog.acme">
         <pubDate>2016-06-29T10:13:10+01:00</pubDate>
         <locators>
            <locator platform="web" action="open" url="http://www.acme.com/open/10054611"/>
            <locator platform="web" action="play" url="http://www.acme.com/play/10054611"/>
            <locator platform="atv" action="open" url="myATVApp://media/open/10054611"/>
            <locator platform="atv" action="play" url="myATVApp://media/play/10054611"/>
            <locator platform="ios" action="open" url="myApp://media/open/10054611"/>
            <locator platform="ios" action="play" url="myApp://media/play/10054611"/>
         </locators>
         <playableProperties>
            <closedCaptioning>en-US</closedCaptioning>
            <audioFormats>DD5.1,DD7.1,AAC</audioFormats>
            <primaryLocale>en-US</primaryLocale>
            <videoQuality>uhd</videoQuality>
         </playableProperties>
         <offers>
            <offer>
               <offeringType>subscription</offeringType>
               <windowStart>2020-06-30T10:00:00+01:00</windowStart>
               <windowEnd>2045-10-13T10:00:00+01:00</windowEnd>
            </offer>
            <offer>
               <offeringType>free</offeringType>
               <windowStart>2022-07-01T10:00:00+01:00</windowStart>
               <windowEnd>2022-07-30T10:00:00+01:00</windowEnd>
            </offer>
         </offers>

Set up content offers with tiers

Tiers are only supported for Video App Integrations, not Apple Subscription Video services. The UMC Availability 3.0 spec and higher use availabilityType to support tiered subscription models. Tiers must be set both on the client app side and supplied to Apple via the subscription registration API and in the service availability feeds as part of the <offer> block of each relevant item.

It is your responsibility to update the subscription anytime the user entitlements change, such as when the user purchases a new add-on, removes an add-on, cancels a subscription, or signs out of the app. When registering a subscription with tiers, set the access level, tiers, and billing identifier, if applicable.

The billingIdentifier is only used for regional content restrictions, most often for live sports, where some events are available to viewers only in specific regions of the same country. It is generally a hashed zip code.

The tiers and access level values must match the values provided in your availability feed, including casing.

subscription.accessLevel = .paid
subscription.tierIdentifiers = [“Tier1”, “Tier2”]
subscription.billingIdentifier = hashedBillingIdentifier

For more information, see the VSSubscription header file (or go directly to the subsection on tier identifiers). Also review the Subscription Registration section on implementing APIs in the UMC Style Guide and the content offer restrictions section in the UMC Availability Data Specifications.

Set up offers and tiered content

Set up content offers with tiers

{{ modalHeader }}