Catalog Ingestion Best Practices
Use these best practices when integrating your catalog on Fire TV.
- Use a unique
IDfor all content. When you update an existing catalog, the IDs for your content should not change. If an
IDdisappears from your catalog, it is removed from Amazon's index. If the content returns later, it should have the same
IDas before. Avoid changing ID's and ID schemes after Amazon has ingested your catalog. If you change
IDschemes after ingestion, any matching Amazon has done with other content is removed. If you change IDs after launch, your catalog will be suspended.
- To launch a work with a specific configuration of video quality, audio language, and subtitles (or any subset of those three), use the
LaunchIddoes not have a required format, but your app's logic must understand the format. When customers launch content from your app, Fire TV launches the class indicated in the broadcast. It also passes the
LaunchId, as configured in the catalog, to your app.
- To specify whether your content is dubbed, original, and/or has subtitles, use the
Subtitleelements. Include as many elements as needed to specify the work's available alternatives. This helps Amazon shows the correct language information to customers.
- Use the
Creditselements to help with content matching. It is important to use these elements in instances where you have the same titles for different works - Amazon uses these elements to determine if the work is a duplicate.
- All work in your catalog should contain at least one offer under
Offers. Offers allow a customer to play a given work. You can define a
FreeOfferif the work is free to view, and a
SubscriptionOfferit requires a subscription to view. Use only one of each offer type for a work in a given time window.
- Televised series made up of seasons and episodes must follow the
TvEpisodehierarchy. You should have only one
TvShowentry for a given televised series. A
TvShowcan have multiple
TvSeasonentries that are linked by
ShowID. If a
TvSeasondoes not have a clear number, you can use the unique air date. A
TvEpisodeentry links to a
ShowID. Similarly, the
- Televised events that do not belong to the traditional show-season-episode television hierarchy can be exported as a
Movie. You should only do this for one-time events, such as a holiday special.
- Use the
ExternalIDelement to share identifiers for your content used in an external source, such as IMDb. Amazon uses this value in content matching. By comparing content against other catalogs, Amazon can determine whether they are the same, leading to better discoverability.
- Prioritize relevant and searchable content in your catalog export. Having content that may no longer be relevant to customers, such as news, can impact the discoverability of the rest of your content. Any work that is under 10 minutes in length will not be ingested. The size of your catalog has an impact on the time taken in acceptance testing.
- New updates to your catalog are not immediately available to customers. Content can take up to 14 hours before appearing to customers after your catalog upload. Define the
MetadataAvailabilityDatefor any work to hide it until a given date. Combining
WindowStartwill show information at the time of premiere.
- Verify deep linking behavior for all user states. After you finish your Launcher integration, validate it by running through the test cases listed in Step 2: Verify Deep Links from the Catalog. Specifically, make sure when a customer selects content, the app launches directly into the expected screen based on the Android intent. The video playback screen should appear if the app sent the playback intent and the sign-in or sign-up screen should appear if the app sent the sign-in intent. Validating the correct behavior facilitates your app's acceptance to the Appstore.
- Verify The Buy Box populates properly based on entitlement.
- If the user has your app installed and they are signed in, your content should appear on the main screen as Watch Now with <your app>.
- If your app contains the content, but the user doesn't have your app installed or they aren't signed in, your app might appear on the main screen or within More Ways to Watch.
- If your app is also a Prime Video Channel, verify the following correct behavior:
- If a user subscribed through your app and not the Prime Video Channel, the app should appear on the main screen as Watch Now with <your app>.
- If your app is also a Prime Video Channel and the user doesn't have your app installed, the Prime Video Channel might appear in the buy box if it's a less expensive option or if it includes a free trial.
- For more information on the buy box and to verify that it is correctly populated, see The Buy Box.
Last updated: Mar 24, 2023