Developer Console
Sign In
Sign In
Developer Console

TV Input Framework on Fire TV

The linear TV integration is based on the Android documentation for developing a TV input service. The following links and explanations help you understand the technical requirements specific to Fire TV.

Background knowledge and terms

Before starting with live TV on Fire TV, review the following documentation for background knowledge.

The linear TV integration is based on the following Android documentation: Develop a TV input service.

Integration details

To integrate live channels, you must provide access to the customer's channel entitlements along with the required metadata.

Live channel entitlements

You must update your app to push only entitled channels into the local channels database on the device, provided by the TV Input Framework (TIF). You can update, add, or remove a channel by registering a broadcast receiver using the INITIALIZE_PROGRAMS action. Make sure you update this entitlement metadata when your app is initially installed. You can do this update even when your app is in the background. For an example of registering a broadcast receiver to handle the INITIALIZE_PROGRAMS action, see Registering a BroadcastReceiver to listen for the INITIALIZE_PROGRAMS action.

To edit your channels, see Work with Channel Data.

If there are channels in this database, the customer can view them. You can add or remove channels from this database at any time. The changes immediately reflect in the UI because the database is the authority for all channels displayed to the customer in any live experience.

Fill out the channel columns in TvContract.Channels as completely as possible. If you know your Gracenote channel IDs or prefer to provide deep links for playback, include that information in Channels#COLUMN_INTERNAL_PROVIDER_DATA as outlined in the code examples section.

Obtain programming metadata

You have two ways to provide metadata for live TV.

  • Use an Amazon Catalog Data Format (CDF) Station ID (preferred)
  • Use a Gracenote channel ID

Provide a CDF Station ID (preferred)

If you provide a CDF Station ID, the information syncs to the cloud daily through the live TV app. If the CDF Station ID is found, it is used when looking up a channel in the Fire TV catalog, which contains up to 14 days of programming information. This information appears in the Home and Live tabs, as well as in the Channel Guide. It automatically refreshes to stay current and is discoverable through Search and Alexa.

Provide a Gracenote ID

If you provide a Gracenote channel ID (either onTV or GVD), the information syncs to the cloud every day through the live TV app. If the Gracenote ID is found, it is used when looking up a channel in the Fire TV catalog, which contains up to 14 days of programming information. This information appears in the Home and Live tabs, as well as in the Channel Guide. It automatically refreshes to stay current, and is discoverable through Search and Alexa.

Channel ordering

Channel ordering determines the rank of channels displayed through the Fire TV device UI. The provider determines the baseline order. However, customers can favorite channels using the context menu or channel manager. These channels have the highest display priority. Therefore, the priority is: favorites > channel ordering option. Fire TV offers the following two options with varying levels of development work:

  • Display name ordering: The most common order because it doesn't require any development time. By using this ordering, the channels in the Fire TV UI are displayed in Unicode according to the displayName. For example, the channel list {"XYZ", "1BC", and "1 BK"} are ordered as {"1 BK", "1BC", "XYZ"}.

  • Custom channel ordering: By using this ordering, provider channels are displayed in the order that align with the "_id" in tv.db, which is assigned by the insert order. You must maintain the channel ordering when updating those channels in tv.db, because the live TV app honors that same order in the Fire TV UI.

For a consistent experience, Fire TV recommends that you choose a channel order that best mimics the order found inside your app. Work with your Amazon representative to select a channel ordering method as part of your onboarding process.

Full screen playback

Fire TV offers the ability to use your own app for full screen playback. To do this, provide a deep link Intent as part of the channel information for the channel database. When a user selects the channel during browse or search, this Intent launches. Whenever the Intent activates, full-screen playback of the requested channel starts. For reference, see Code examples.

Guidelines for the splash screen

  • It should take a maximum of three seconds for the splash screen to initiate after the user focuses on a tile.
  • Video preview for focused content should begin playing two seconds after the splash screen loads.
  • If your app supports channel preview (recommended), and a user enabled parental controls in their Fire TV settings, channel preview is disabled (no playback in mini-detail) and reverts to the image coverage that Gracenote already includes. Amazon doesn't block the channel preview based on content ratings or preferences set up in Fire TV or your app. This rule applies to all partners and live sources.

Parental controls

Based on the product requirements, if a user enabled parental controls (PCON), you shouldn't play preview videos.

If your app renders content onto the surface provided to your TvInputService object (for example, live preview or no channel deep linking), you must properly implement parental controls. This makes sure that when parental controls are enabled, content isn't displayed to the user without first requesting they enter a PIN. It's the responsibility of your TvInputService to notify the foreground app whenever a user requests content that should be blocked. For the suggested flow, see Honor parental controls.

Provider attribution

Make sure you customize the following three items.

1. Label

By default, your app's label attribute is used as the header when users browse your channels. This label should be no longer than 12 full-width or 24 alphanumeric characters. If you prefer another name, but you can't change the label, work with your Amazon representative to make sure this is overridden.

Make sure you provide a single monochrome logo (white image, transparent background) for your app's branding. The logo is overlaid on top of your program art. This image file must be up to 34px high with a maximum width covering 25 percent of the overlaying image in a horizontal orientation.

Contact your Amazon representative for details.

3. Banner

Provide an app banner through the package manager. For an example, see Code examples.

Certification checklist

Amazon uses the following checklist to certify your app as live TV integrated. Your app's implementation directly impacts the expected behavior. Amazon handles exceptions to the certification on a case-by-case basis.

Entitlement state changes

  • Customer-entitled channels populate in the Fire TV UI (such as the On Now row or the Channel Guide), after a customer performs one of the following actions:
    • Opens and signs in to the app
    • Accesses the app's setting page when going to Settings > Live TV > Sync Sources > App Name

    You must handle both conditions.

  • If a customer's membership expires and changes to an "unentitled" status, the channels continue to be part of the Fire TV UI until a customer selects a channel, views the paid offer and exits, or declines the offer.
  • Channels are removed from the Fire TV UI when a user uninstalls the app or if the user becomes unentitled to those channels.

Maximum rate of rollout

Perform a staged rollout of channels to your customers at a maximum rate of 500k per hour.

This value refers to the number of customer Fire TV devices with channel entitlement. Channel entitlement means one click to full-screen playback from Fire TV Linear Integration UX.

Examples

  • App ABC offers video-on-demand, but has live TV as a premium add-on. The rate would refer to ABC customers that have the live add-on only.
  • App XYZ has a free baseline package of channels and a second paid tier that includes more channels. If the channel lineup of the paid tier is updated, this rate refers to those customers in that paid tier.

Browse and playback experience

  • A rich metadata experience is available when customers focus on a channel. In the linear TV guide, the channel includes the channel logo, channel number (optional), and scheduling information for the next 14 days. Program metadata includes the program name, time of playback, episode name, episode description (long), season and episode information, closed captions, rating, program image (16:9), and background image (16:9). This metadata information should come from Amazon catalog matches (CDF or Gracenote) or metadata that is pushed as part of the TV contract.
  • When a customer focuses on a channel in the On Now row, they can see a live channel preview that replaces the background image.
  • A customer should understand who is providing this entitled channel. This includes adding provider attribution as either part of the background image (monochrome, 34px height) or as a splash screen before playing a live channel preview.
  • Selecting a channel brings the customer to full-screen playback. The Back button returns the user to the Fire TV UI in two button presses or less.
  • If parental controls (PCON) is enabled, a PIN prompt shows before playback. If PCON is enabled, you must disable live channel preview.
  • Reduce the audio volume of live playback if the user accesses Alexa. Video playback should continue.
  • (Recommended) A genre can be attributed to a channel so that the channel shows up in additional ingress points in the Fire TV UI.

Development, staging, and deployment

  • Amazon must have the ability to add specific accounts to an allow list to review and certify the integrated experience before going to production.
  • Only entitled channels are added to Fire TV UI in the marketplaces that both parties have agreed to launch. Subsequent launches in new marketplaces will constitute as a new certification review and require being added to an allow list.
  • Amazon must understand any channels that you add or remove post-launch. Both parties must agree on a maximum limit on channels added.
  • (Recommended) The download page and release notes of the app should mention live TV integration so that customers understand the new feature availability on Fire TV.

Making updates

For any app updates, go through the items in the certification checklist again before making the update.

For any channel lineup updates, go through the items in the certification checklist again, plus do the following:

  • Inform your Amazon representative of your launch timeline at least two weeks before launch.
  • If you are adding or subtracting 10 percent or more of your lineup, get explicit approval from your Amazon representative.

Last updated: May 05, 2025