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 will help you understand the technical requirements specific to Fire TV.

Background Knowledge and Terms

The following external links are useful for background and a basic understanding before you deep dive into live TV on Fire TV. Review this documentation before proceeding with your integration:

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

Integration Details

To integrate live linear channels, you must provide access to the customer's channel entitlements along with the metadata required to deliver a content-forward browse and search experience across Fire TV.

Live Channel Entitlements

Your application must be updated to push only entitled channels into the local channels database on the device (provided by the TV Input Framework (TIF)). You can update (or add or remove), a channel by registering a broadcast receiver using the INITIALIZE_PROGRAMS action. Ensure this entitlement metadata is updated when your application is initially installed. This can be done even while your application is in the background.

To edit your channels, see Work with Channel Data.

If there are channels in this database, the customer can view them. Channels can be added or removed from this database at any time, and the changes will be immediately reflected in the UI. The reason for this is 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 deeplinks for playback, include that information in Channels#COLUMN_INTERNAL_PROVIDER_DATA as outlined in the code examples section.

Obtaining Programming Metadata

In order to provide metadata for Live TV, you will use the Gracenote channel ID.

Providing a Gracenote ID

When you provide a Gracenote channel ID (either onTV or GVD), the information will sync to the cloud everyday through the live TV app. If the Gracenote ID is found, it will be used when looking up a channel in the Fire TV catalog, which contains up to 14 days of programming information. This information will appear in the Home and Live tabs, as well as in the Channel Guide. It will automatically refresh to stay current, and will be 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 via the context menu or channel manager. These channels will have the highest display priority. Therefore, the priority is: favorites > channel ordering option. Fire TV offers two options with varying levels of development work:

  1. Display name ordering has historically been the most common order as it requires zero development time. By using this ordering, the channels in the Fire TV UI will be displayed in unicode according to the displayName. For example, the channel list {“XYZ”, “1BC”, and “1 BK”} will be ordered as {“1 BK”, “1BC”, “XYZ”}.

  2. Custom channel ordering is your second option. By using this ordering, provider channels will be displayed in the order that align with the “_id” in tv.db, which is assigned by the insert order. You will need to maintain the channel ordering when updating those channels in tv.db, since the Live TV app will honor that same order in the Fire TV UI.

For a consistent experience, we highly recommend you choose a channel order that best mimics the order found inside your application. Work with your Amazon contact to select a channel ordering method as part of your onboarding process.x

Full Screen Playback

Deeplinking. Fire TV offers the ability to use your own application for full screen playback. To do this, provide a deeplink Intent as part of the channel information for the channel database. When the channel is selected during browse or search, this Intent will be launched. Whenever the Intent is activated, full-screen playback of the requested channel will be initiated. See the code sample section for reference.

Guidelines for the splash screen

  • It should take a maximum of 3 seconds for the splash screen to initiate once the user has focused on a tile.
  • Video preview for focused content should begin playing 2 seconds after the splash screen has loaded.
  • If a partner supports channel preview (strongly recommended), and Parental Controls (PCON) is enabled via a customer's FTV settings, channel preview will be disabled (no playback in mini-detail) and will revert to image coverage that is already included with Gracenote. Amazon is not blocking on content ratings or preference set up in FTV or the partner app. This rule applies to all partners and live sources.

If your application supports channel preview (strongly recommended), and PCON is enabled via FTV setting by customer, then channel preview will be disabled (no playback in mini-detail) and will revert to image coverage that is already included with Gracenote. We do not block on content ratings or preference set up in FTV or the partner app. This rule applies to all partners and live sources.

Parental Controls

Based on the product requirements, you should not play preview playback videos if Parental Controls (PCON) are enabled.

If your application renders content onto the Surface provided to your TvInputService (i.e., live preview or no channel deeplinking), it is required that parental controls are implemented properly. This ensures content is not displayed to the end user without first requesting to enter a PIN when parental controls are enabled. It is the responsibility of your TvInputService to notify the foreground application whenever content is requested that should be blocked. See the code sample section for the suggested flow.

Provider Attribution

Make sure you customize these three items:

1. Label

By default, your application's label will be used as the header when customers browse your channels. This label should be no longer than 12 full-width or 24 alphanumeric characters. Work with your Amazon contact to ensure this is overridden if you prefer another name, but you cannot change the label.

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

Reach out to your Amazon contact for details.

3. Banner

Provide an application banner through the package manager. Please see the code sample section for an example.

Certification Checklist

Amazon will be using the following checklist as to certify your application as Live TV integrated. Your application's implementation directly impacts the expected behavior points below. Note that any exceptions to the certification will be handled on a case-by-case basis.

Entitlement State Changes

  • Customer-entitled channels populate in the Fire TV UI (for example, "On Now" row, Channel Guide) after a customer performs one of the following: (1) opens and signs into the application or (2) accesses the application's setting page when going to Settings > Live TV > Sync Sources > <Application Name>. The developer must check both of these conditions.
  • If a customer's membership expires (that is, turns to an "unentitled" status), the channels will continue to be part of the Fire TV UI until a customer ingresses into a channel, views the pay wall, and backs out or declines the offer.
  • Channels will be removed from the Fire TV UI when the application is uninstalled or if those channels become unentitled.

Maximum rate of rollout

Perform a staged rollout of channels to your customers at a maximum rate of 500k / 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 will be available when customers are focused on a channel. In the linear TV guide, the channel will include 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 & episode information, closed captions, rating, program image (16:9), and background image (16:9). This metadata information should come from Gracenote matches or metadata that is pushed as part of the TV contract.
  • When a customer focuses on a channel in the "On Now" row, he or she 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, 34 px height) or as a splash screen prior to live channel preview playback.
  • Selecting a channel will bring the customer to a full-screen playback. The Back button will return to the Fire TV UI in no more than two button presses.
  • A PIN prompt will show prior to playback if Parental Controls (PCON) is enabled. Live channel preview must be disabled if PCON is enabled.
  • Reduce the audio volume of live playback if Alexa is accessed; video is expected to continue.
  • (Optional) A genre can be attributed to a channel so that the channel will show 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 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 are added and removed post-launch. Both parties must agree on a maximum limit on channels added.
  • (Highly recommended) The download page and release notes of the application 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 Fire TV contact of your launch timeline at least two weeks prior to launch.
  • Get explicit approval from your Fire TV contact if you are adding or subtracting 10% or more of your lineup.

Last updated: Jul 16, 2024