Deliver Content

Deliver previews and bonus content

Extras overview

Trailers (previews), bonus, and additional content that are typically related to another movie or TV show, are classified as “extra” content. Specify a content item as extra by setting the <contentType> value to extra in the catalog and availability feeds.

The Apple TV app supports playback and display of extra content for Apple Subscription Video service providers who have qualified for delivery. Contact your Apple Business Development Representative to initiate the qualification process. Extra content is currently not supported for Video App integrations.

Once you are cleared to deliver extra content for your Apple Subscription Video service, make sure you properly prepare your asset deliveries and accurately provide catalog and availability data.

Delivering previews

A preview is a promotion for related content that contains montage, clip-based, or segment footage — or a combination of that footage. Previews can be delivered for movies or TV shows. Previews can be rejected by quality control (QC) if they do not meet the specified standards.

Business policy and minimum requirements

  • Delivering territories for previews is not supported.
  • Background videos for previews are not supported. The first available trailer will play as a background video.
  • Defined previews are not supported.
  • Previews must accurately represent the full featured asset.
  • Previews must be between 30 seconds and 10 minutes in length.
  • Previews must not contain nudity or graphic sexual material.
  • Audio of previews must match an audio language present in the featured asset.
  • Previews must be suitable for all territories where they are made available.

How to deliver preview assets 

As with other Apple Subscription Video content, you should deliver your preview as an iTunes Package (.itmsp) via Transporter. Each preview video asset must be delivered in its own .itmsp package, separate from related content assets. At a minimum, the .itmsp package must include a metadata.xml file, video source, and captions (required only for U.S. deliveries). You can deliver other components, such as subtitles or alternate audio as needed.

In the metadata.xml file, preview video assets are delivered using the <subtype> tag and the asset type must be specified as preview. You must also supply a unique content ID (<umc_content_id>) for the preview in the metadata.xml file. That content ID must be referenced in the catalog and availability feeds using an item’s contentId attribute. You can leverage the variant ID in the metadata.xml asset file and availability feeds to deliver different versions of preview video assets for different territories while using the same catalog record.

Preview deliveries should follow preview source delivery specifications. 

Keep the following in mind when delivering a preview:

  • While you can have multiple previews for a single TV show or movie, each preview must be delivered in its own package with a unique content ID. You can’t deliver multiple preview assets with the same content ID.
  • If you deliver a package with subtype set to preview, you cannot also deliver a full video source file in the same package.
  • If you exclude subtype on a preview asset, the content will not be playable in the Apple TV app and cannot be resolved via redelivery or asset replacement. Do not exclude subtype on assets that should be previews.

Here is an example metadata.xml file for a preview:

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://apple.com/itunes/importer" version="subscriptionvideo5.0">
    <language>en-US</language>
    <provider>AppleseedEntertainment</provider>
    <video>
        <subtype>preview</subtype>
        <umc_catalog_id>com.catalog.acme</umc_catalog_id>
        <umc_content_id>NEW_AWESOME_TV_SHOW_1234_TRAILER</umc_content_id>
        <umc_variant_id>1</umc_variant_id>
        <title>Preview: New Awesome TV Show</title>
        <original_spoken_locale>en-US</original_spoken_locale>
        <assets>
            <asset type="preview">
                <data_file role="source">
                    <locale name="en-US"/>
                    <file_name>33bard5f917-preview-source.mov</file_name>
                    <size>2595225600</size>
                    <checksum type="md5">fe82a79dd93a89b499aa211ab4603773</checksum>    
                    <attribute name="crop.top">0</attribute>
                    <attribute name="crop.bottom">0</attribute>
                    <attribute name="crop.left">0</attribute>
                    <attribute name="crop.right">0</attribute>
                </data_file>
                <data_file role="captions">
                    <locale name="en-US"/>
                    <file_name>33bard5f917—preview-english.scc</file_name>
                    <size>9511</size>
                    <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum>
                    <attribute name="program.start.timecode">-01:00:00:00</attribute>
                </data_file>
            </asset>
        </assets>
    </video>
</package>


How to set up feed data for previews 

Your preview should be included in both your catalog and availability feeds in order for it to go live.

The catalog entry for your preview should include all of the required information outlined in the catalog specifications for extras, in the order listed on the specifications document. 

The contentType should be set to extra and extraInfo should be set to preview in the catalog feed. Although the block for relatedItem is listed as optional in the specifications, you will need to provide this information in order for the preview to be associated with the correct catalog movie or TV show, which is included in the same catalog feed. You can also specify the order previews will appear in the Trailers row on the Apple TV app. This can be adjusted per market if needed.

Previews are also required to have a keyframe (tile_artwork) delivered via the catalog feed. This artwork is a 16:9 image that represents the preview and should be a keyframe from the playable asset or a production still. For more information, see Artwork Specifications.

Here is an example of a preview in the catalog feed. This can be paired with the metadata.xml example from the preview asset delivery section above.

<item contentType="extra" contentId="NEW_AWESOME_TV_SHOW_1234_TRAILER">
    <pubDate>2020-08-13T09:51:33+01:00</pubDate>  
    <title locale="en-US">Preview: New Awesome TV Show</title>
    <title type="additional" locale="en-US">Preview</title>
    <genre>drama</genre>  
    <rating systemCode="us-tv" value="TV-Y7" />
    <rating systemCode="de-tv" value="6+" />
    <advisory systemCode="us-tv">L</advisory>
    <advisory systemCode="us-tv">S</advisory>
    <advisory systemCode="us-tv">V</advisory>
    <credit role="actor" order="1">
        <name>Ted Green</name>
    </credit>
    <credit role="actor" order="2">
        <name>Jeff Brown</name>
    </credit>
    <artwork url="https://www.acme.com/imageassets/B012345/keyframe1.jpg" type="tile_artwork" />
    <extraInfo>
        <type>preview</type>
        <duration>180</duration>
        <network>My Network</network>
        <relatedItem relatedContentType="tv_show" relatedContentId="NEW_AWESOME_TV_SHOW_1234">
            <orderNumber>1</orderNumber>
            <orderNumber country="DE">2</orderNumber>
        </relatedItem>
    </extraInfo>
</item>

You can control the availability of your preview in your availability feed. As with other items in the availability feeds, use the same content ID for the preview item provided in the catalog feed and the asset’s metadata.xml file.

If you want previews to be available to all users and not just subscribers to your service, apply free offers to your previews. Applying subscription offers will restrict playback to subscribed users only.

This example availability feed, showing the offeringType set to free, can be paired with the catalog feed example above.

<item contentType="extra" contentId="NEW_AWESOME_TV_SHOW_1234_TRAILER" catalogId="com.catalog.acme" variantId="1">
    <pubDate>2020-08-13T09:51:33+01:00</pubDate>
    <playableProperties>
        <closedCaptioning>en-US</closedCaptioning>
        <audioFormats>DD5.1,AAC,ATMOS</audioFormats>
        <primaryLocale>en-US</primaryLocale>
        <videoQuality>hd</videoQuality>
    </playableProperties>
    <offers>
        <offer>
            <offeringType>free</offeringType>
            <windowStart>2020-09-01T00:00:01+01:00</windowStart>
            <windowEnd>2021-09-01T00:00:01+01:00</windowEnd>
        </offer>
    </offers>
</item>

If the TV show or movie associated with your preview is not yet available, you will still need to ensure the TV show or movie record is included in the catalog feed. You can apply a Coming Soon offer to the TV show or movie in the availability feed to bring the Apple TV app content page live in advance of release. 

Learn more about setting up Coming Soon offers

Delivering bonus content

Bonus content is value-added material, such as sneak peeks and behind-the scenes footage, related to a movie or TV show. Bonus content behaves the same as the movie or TV episodes it is attached to, respecting the offer type. Bonus content can be rejected by quality control if it does not meet the specified standards.

Business policy and minimum requirements

  • Bonus content must be a minimum of 30 seconds in length.
  • Bonus content should be related to the TV show or movie.

How to deliver bonus content assets

Bonus content must be delivered in a separate iTunes Package (.itmsp). At a minimum, it must include a metadata.xml file and video source. Captions are optional but recommended (required for U.S. deliveries). You can deliver other components, such as subtitles or alternate audio, as needed. Bonus content assets should be full source deliveries.

In the metadata.xml file for the bonus content, supply a unique content ID (<umc_content_id>) for the item. That content ID must be referenced in the catalog and availability feeds using an item’s contentId attribute. To deliver different versions of bonus content across different territories while using the same catalog entry, use a variant ID in the metadata.xml file and availability feeds. 

Here is an example metadata.xml file for a bonus content asset delivery.

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://apple.com/itunes/importer" version="subscriptionvideo5.0">
    <language>en-US</language>
    <provider>AppleseedEntertainment</provider>
    <video>
        <umc_catalog_id>com.catalog.acme</umc_catalog_id>
        <umc_content_id>BONUS_1</umc_content_id>
        <umc_variant_id>1</umc_variant_id>
        <title>Bonus 1</title>
        <original_spoken_locale>en-US</original_spoken_locale>
        <assets>
            <asset type="full">
                <data_file role="source">
                    <locale name="en-US"/>
                    <file_name>33bard5f917-bonus-source.mov</file_name>
                    <size>2595225600</size>
                    <checksum type="md5">fe82a79dd93a89b499aa211ab4603773</checksum>    
                    <attribute name="crop.top">0</attribute>
                    <attribute name="crop.bottom">0</attribute>
                    <attribute name="crop.left">0</attribute>
                    <attribute name="crop.right">0</attribute>
                </data_file>
                <data_file role="captions">
                    <locale name="en-US"/>
                    <file_name>33bard5f917—bonus-english.scc</file_name>
                    <size>9511</size>
                    <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum>
                    <attribute name="program.start.timecode">-01:00:00:00</attribute>
                </data_file>
            </asset>
        </assets>
    </video>
</package>

How to set up feed data for bonus content 

Your bonus content should be included in both your catalog and availability feeds in order for it to go live.

The catalog entry for bonus content should include all of the required information outlined in the catalog specifications for extras, in the order listed in the specifications document. 

The <contentType> value should be set to extra and the <extraInfo> value should be set to bonus in the catalog feed. Although the <relatedItem> block is listed as optional in the specifications, you will need to provide this information in order for the bonus content to be associated with the correct catalog movie or TV show, which is included in the same catalog feed. You can also specify the order bonus content will appear in the Bonus Content row on the Apple TV app. This can be adjusted per market if needed. 

Bonus content is also required to have a keyframe (tile_artwork) delivered via the catalog feed. This artwork is a 16:9 image that represents the content and should be a keyframe from the playable asset or a production still. For more information, see Artwork Specifications. 

Here is an example of a bonus content item in the catalog feed. This can be paired with the metadata.xml example from the asset delivery section above.

<item contentId="BONUS_1" contentType="extra">
        <pubDate>2020-05-01T18:00:12-07:00</pubDate>
        <title locale="en-US">Bonus 1</title>
        <extraInfo>
            <type>bonus</type>
            <relatedItem relatedContentId="SHOW_1" relatedContentType="tv_show"/>
        </extraInfo>
</item>

You can control the availability of your bonus content in your availability feeds. As with other items in the availability feeds, use the same content ID for the bonus content provided in the catalog feed and in the asset’s metadata.xml file.

If you want bonus content to be available to subscribed users only, apply subscription offers to your bonus content in the availability feed. Applying free offers allow access to all users regardless of subscribed status.

This example availability feed, showing the offeringType set to subscription, can be paired with the catalog feed example above.

<item contentType="extra" contentId="BONUS_1" catalogId="com.catalog.acme" variantId="1">
        <pubDate>2020-05-01T18:00:12-07:00</pubDate>
        <offers>
            <offer>
               <offeringType>subscription</offeringType>
               <windowStart>2020-09-01T02:00:00+01:00</windowStart>
               <windowEnd>2021-09-30T02:00:00+01:00</windowEnd>
            </offer>
        </offers>
</item>

Related Content

Guides
Apple TV Channels Subscription Video Asset Specification
Review the requirements for the delivery of subscription content assets and examples of XML delivery.
Apple TV Channels Subscription Video Asset Specification