Developer Console
Sign In
Sign In
Developer Console

Catalog Ingestion Best Practices

Use these best practices when integrating your catalog on Fire TV.

General Integration

  • Use a unique ID for all content. When you update an existing catalog, the IDs for your content should not change. If an ID disappears from your catalog, it is removed from Amazon's index. If the content returns later, it should have the same ID as before. Avoid changing ID's and ID schemes after Amazon has ingested your catalog. If you change ID schemes 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 LaunchId element. A LaunchId does 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 AudioLanguage and Subtitle elements. 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 ReleaseYear and Credits elements 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 FreeOffer if the work is free to view, and a SubscriptionOffer it 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 TvShow, TvSeason, and TvEpisode hierarchy. You should have only one TvShow entry for a given televised series. A TvShow can have multiple TvSeason entries that are linked by ShowID. If a TvSeason does not have a clear number, you can use the unique air date. A TvEpisode entry links to a TvShow through the ShowID. Similarly, the SeasonID links the TvEpisode to a TvSeason.
  • 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.

Content Discoverability

  • Use the ExternalID element 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 MetadataAvailabilityDate for any work to hide it until a given date. Combining MetadataAvailabilityDate with WindowStart will show information at the time of premiere.

Launcher Integration

  • 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