Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
The following best practices, code samples, and other references will help you better understand the specifics of live integration during the implementation phase.

Add package to allow list

An allow list determines which apps are capable of surfacing their channels in the Fire TV browse and search.

Best practices

The following product and implementation guidelines will help provide your customers with the best live TV experience on Fire TV:
  • Provide a friction-free sign-up to encourage trial where applicable. Examples include simplifying registration forms on the app or using a phone number to sign up.
  • Use a transparent, monochrome logo for each TvContract.Channels.Logo in your channel lineup.
  • Optimize the deep-link flow to begin full-screen playback in less than 2.5 seconds.
  • Use bulk actions anytime you are manipulating more than one channel.
  • Leverage Amazon Catalog where applicable to simplify integration.
  • Focus on metadata loading performance optimizations over having full schedule availability or preferred image sizes.
  • Use JobScheduler or WorkManager to periodically verify entitlements are always accurate. This makes sure your channels in browse and search are in sync with the entitled channels at all times, even if your app is not in the foreground.
  • With the exception of a custom channel order, update your entitled channel list in place is preferred to removing and re-adding all channels if the entitled channel list has changed slightly.
  • Provide the channel display name in COLUMN_DISPLAY_NAME that will be presented in the Fire TV UI. Fire TV displays up to 25 alphanumeric characters, but won’t display the full channel name if the length exceeds this limit. This max limit is applicable for both half-width and full-width character sets. Example of one that won’t display: The Walking Dead Universe (Max length-Pass) / Short Name (Pass)/ Extremely Long Station Name (Fail)/ 韓流・華流韓流・華流韓 (Max length-Pass).
  • Before performing any modifications, query the TV Input Framework (TIF) database each time to determine which channels are already in the database.
  • Before inserting a channel, make sure it is not already present. If the channel is already present, check the metadata to see if it is up-to-date. Only if metadata needs to be updated should a database update operation be executed.
  • The database cursor should be checked to be null. If the cursor is null, send a delete request for all channels with your input ID, and then reinsert channels.

Code examples

This section contains example code related to live TV integrations. The following code shows how to include an Amazon catalog station ID and deep link into the TV database.
The following code shows how to include a Gracenote ID and deep link into the TV database.

Honor parental controls

The following code demonstrates how to listen to parental controls for live preview playback.

Providing an application banner

To show your application banner in live TV settings, you must provide an application banner through the package manager.
To test the banner, review the following example code.

Registering a BroadcastReceiver to listen for the INITIALIZE_PROGRAMS action

The following code demonstrates how to include a <receiver> element in AndroidManifest.xml with an intent filter to listen for the INITIALIZE_PROGRAMS action.
Create a receiver class which extends BroadcastReceiver and implement the onReceive method. This is where you can include the initialization logic to push only entitled channels into the local channels database provided by the TIF.
You can find a complete example of the implementation in the Sample Live TV App. To test the implementation, choose one of the following assumptions:
  • Assuming the device is already connected and the APK hasn’t been side loaded yet, open a new terminal and run adb logcat with the appropriate filters to see any logs relevant to the onReceive logic. In a separate terminal, run adb install <path-to-apk>. After the installation succeeds, the relevant logs should begin appearing since INITIALIZE_PROGRAMS is broadcast when a new TV Input is added.
  • Assuming the APK is being replaced (apk install -r <path-to-apk>), the INITIALIZE_PROGRAMS action doesn’t broadcast automatically. To test the onReceive logic, refer to this code snippet:

Sample live TV app

A sample app with live TV integration is available on GitHub at github.com/amzn/ftv-livetv-sample-tv-app. This sample TV app is based on the Google sample TV app. You can use this sample app as a reference for the live TV integration on Fire TV. To load the sample app
  1. Go to https://github.com/amzn/ftv-livetv-sample-tv-app, click Clone or download, and then click Download ZIP. Unzip the download. The app shows sample code for integrating live TV. To see the result, use ADB to sideload the app-debug.apk file onto your Fire TV, as described in the following steps.
  2. Connect to Fire TV through ADB. If you’ve already turned on debugging and have ADB installed, just get your Fire TV’s IP address from Settings > Device & Software (or My Fire TV) > About > Network and run the following, customizing the IP address for your own Fire TV: Replace with your Fire TV’s IP address. (If you have trouble connecting and you’re on your corporate VPN, try disconnecting from VPN, since your computer needs to be on the same wifi network as your Fire TV.)
  3. Install the built APK in the sample app.
    The response is as follows:
    Note that this sample app does not launch as a standalone app in the traditional sense. Instead, it incorporates code for live TV channels available from the Fire TV device.
  4. On your Fire TV device, go to Settings > Applications > Manage Installed Applications. Select Sample TV Inputs. Then click Launch application.
    Sample TV inputs

    Sample TV inputs

    This will take you to the Amazon developer portal.
    Amazon Fire TV site

    Amazon Fire TV site

  5. On your Fire TV remote, press the Home button to back out of this screen. Then go to Settings > Live TV > Sync Sources > Amazon Sample TV Input. This will load the sample channels.
    Syncing sources

    Syncing sources

  6. After the sync finishes, press the Home button. Channels should now be visible in the On Now row and Guide. Here’s the On Now row:
    Fire TV 'On Now' row

    Fire TV 'On Now' row

    Here’s the Channel Guide.
    Fire TV Channel Guide

    Fire TV Channel Guide

    To navigate to the Channel Guide on Fire TV, go to your Home screen, scroll down to the On Now row, press the menu button on your remote, and then click Channel Guide. You can also press the microphone button on your remote and say, “Channel Guide.”
Last modified on May 27, 2026