Developer Console
Gracias por tu visita. Esta página solo está disponible en inglés.

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

You have two ways to provide metadata for Live TV.

  • Use a Gracenote channel ID
  • Insert channel metadata yourself

Keep in mind that this choice must be made for each individual channel. This means you could have one channel that uses a Gracenote ID and another where you insert the channel metadata yourself.

Providing a Gracenote ID (The preferred method)

If you provide a Gracenote channel ID (either onTV or GVD (Global Video Data)), the information will sync to the cloud on a daily basis 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.

No Gracenote ID

If you do not provide a Gracenote channel ID for your channels, you need to insert all Channel metadata, including logos, and regularly insert the upcoming programming information across all of your channels into TvContract.Programs. The Sample Live TV App provides an example of how to do this.

Here are the fields that can be included:

CX Field Description Required for Certification? Associated TIF Field
Program Name Name of the program. This is the large text on the top left of the screen. Y Title
Time of Playback Time it airs (Ex: 11:00 PM – 12:00 AM). Found directly under the program name. Y Start_time_utc_millis
Episode Name Name of the episode that is airing. This is in bold underneath the time of playback and badges. Y Episode_title
Episode Description Description of the episode. Fills in the rest of the section after the episode name. We utilize this long description, but fallback to the short description. Y Long_description fallback to short_description
Season & Episode Information Common in a series (such as a sitcom). This is the season and episode info provided for this airing. This is part of the mini-details after the episode name. N Season_display_number
Rating Local rating of the episode in badge form. In the same line as the time of playback. N content_rating
Closed Captions Badge that indicates if the airing supports closed captions. Found in the same line as time of playback. N Not supported - coming soon
HD Badge that indicates if the airing is shot in HD. Found in the same line as time of playback. N Not supported - coming soon
Live Badge on the carousel tile that indicates the airing is shown in ‘real time’ as it is recorded. N Not supported - coming soon
New Badge on the carousel tile that indicates the airing is the first time it is being aired (but not in real time). N Not supported - coming soon
Program Image 16:9 show / movie image that fills the carousel tile. The resolution should be 768x432 or higher. Y Thumbnail_uri
Background Image 16:9 show / movie image that fills the section of the top right corner next to the mini-details section. The resolution for this should be 1280x720 or higher. Y Poster_art_uri
Channel Name Name of the channel displayed on the tile in the carousel. As per the best practices section, 16 alphanumeric or 8-10 full-width characters are displayed. Y Display_name
Channel Logo Transparent, monochrome logo that is used in the EPG (Electronic Programming Guide). If there is no channel logo, it will fallback to the channel name (in the marquee). Y logo

Channel Ordering

Channel ordering determines the rank of channels displayed through the FireTV 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. FireTV offers three 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. Channel number ordering is determined by the displayNumber field in the Channel class, which is part of the standard Android TV Contract. The channels will be displayed in ascending order by channel number. For this, a channel number must be assigned for each channel during development. Note that other ordering options can be utilized even if channel numbers are assigned.

    Range of digits allowed = 1 up to 5 digits

    Precision of digits allowed = up to 3 decimal places

    Examples: [1.000 - 99.999, 1.00 - 999.99, 1.0 - 9999.9, 1 - 99999]

  3. Custom channel ordering is the third and final 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.

Full Screen Playback

You have two choices to implement here:

  1. Deeplinking (links that open in a particular app)
  2. The native TV application

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.

The native TV application. Another way to implement the full screen playback is by using the native live TV application. This is done through the TvInputService.Session. To see an example of this, see the Sample Live TV App.

Live Preview

Even if deeplink intents are provided, you must implement the TvInputService.Session. When onTune is called, which will happen whenever a customer focuses on one of the tiles in a browse row, you must show a splash screen with your application’s name or logo followed by rendering playback for the requested channel onto the provided secure Surface. This drives engagement. The onTune requests can also be used to capture metrics or act as a hint to start loading the live content to improve performance.

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.

Parental Controls

If your application renders content onto the Surface provided to your TvInputService (i.e., live preview or no channel deeplinking), it is mandatory 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.

You will also need provide a single monochrome logo that represents your application's branding:

  • Logo with Gracenote ID. 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.

  • Logo without Gracenote ID. Populate the COLUMN_POSTER_ART_URI in TvContract.Programs. You will need to burn the monochrome logo into the image. The monochrome logo must be placed (-56, 44) from the top right coordinate.

3. Banner

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

Last updated: Jan 28, 2021