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

You have two ways to provide metadata for Live TV.

  • Use a Gracenote channel ID (preferred)
  • 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.

TIF + Gracenote TIF only
Browse Dedicated Carousel
Live Provider Row
App Peak
Browse Mixed Carousel
Recent
Home On Now
Genre Row
Browse
Electronic Program Guide
Search
Channel
Program
Voice
Tune to
Tune to (New/Live only)
Update method (metadata)
Automatic via Gracenote
Manual (must regularly update info 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:

UX 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
End_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
Episode_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. See best practices for guidance on display naming limitations. 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 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.

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.

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 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 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: Oct 10, 2022