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 other explanations will help you understand the technical requirements specific to Fire TV.
- Background Knowledge and Terms
- Integration Requirements
- Related Topics
Background Knowledge and Terms
The following external links are useful to digest and understand 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)
- 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.
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 should be updated to push entitled channels into the local channels database on the device that is provided by the TV Input Framework (TIF). Channels can be added, updated, or removed at any time, even while your application is in the background. Your application should register a broadcast receiver for the
INITIALIZE_PROGRAMS action to ensure entitlement metadata is updated when your application is initially installed.
To edit your channels, see Work with Channel Data.
The existence of channels in this database implies the customer is entitled to view them. The live TV application on the device will use the database as an authority for all channels displayed to the customer in any of the live experiences. Channels can be added or removed from this database at any time, and the changes will be immediately reflected in the UI.
The channel columns in
TvContract.Channels should be filled out as completely as possible. If you know your Gracenote channel IDs or prefer to provide deeplinks for playback, you can share that information in
Channels#COLUMN_INTERNAL_PROVIDER_DATA as outlined below in the code snippets.
Obtaining Programming Metadata
If you are able to provide your Gracenote channel IDs (either on TV and GVD (Global Video Data)), this information will be synced to the cloud by the live TV app and used to look up the corresponding channel in the Fire TV catalog, which contains up to 14 days of programming information. If the Gracenote ID is found in our cloud, the associated programming information for that channel will appear in the ‘Home’ & "Live" tabs and Channel Guide experiences without any further integration requirements and will automatically refresh itself to stay current. Search and Alexa features will also work out-of-the box.
If you cannot provide a Gracenote channel ID for your channels, you will need to insert all Channel metadata, including logos, and regularly insert the upcoming programming information across all of your channels into TvContract.Programs to the fullest extent possible. The Sample Live TV App provides an example of how this can be achieved.
Channel Deep Linking
Playback of Live TV content is typically handled by the native live TV application on the device by interacting with your
TvInputService.Session. If you would prefer to use your own application for the full screen playback experience, you need to provide a deeplink Intent as part of the channel information inserted into the Channel database. A code sample is provided below for reference. When the channel is selected in any of the browse or search experiences, this Intent will be launched. The expectation is that this Intent should jump into your application and initiate full-screen playback of the requested channel.
It is still required to implement a
TvInputService.Session, even if deeplink intents are provided. When
onTune is called, which will happen whenever a customer focuses on one of the tiles in a browse row, it is highly encouraged to render playback for the requested channel onto the provided secure Surface as this is a key engagement driver. The
onTune requests can also be used to capture metrics or act as a hint to start loading the live content to improve performance.
If your application renders content onto the Surface provided to your
TvInputService, it is critical 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.
By default, your application's
label will be used as the header in browse experiences containing your channels. Work with your Amazon counterpart to ensure this is overridden if you prefer another name but cannot change your label for some reason. You will also need provide a monochrome logo that will be overlaid on top of your program art. This should be 34px high and can be an arbitrary width in a horizontal orientation within reason.
If you don't have Gracenote IDs for your channels, when you populate the
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.