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
- Integration Details
- Certification Checklist
- Making updates
- Related Topics
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:
- Live TV App
- TV Input Framework (TIF)
- TvInputService
- TV Channels
- Android Sample Tv Input Application
- Gracenote ID
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 |
✓ | |
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:
-
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”}. -
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:
- Deeplinking (links that open in a particular app)
- 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.
2. Logo
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.
Related Topics
Last updated: Oct 10, 2022