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

Live TV Integration

Fire TV offers a variety of live browse, voice, and search experiences to help customers discover and enjoy the content they love. The live TV integration is primarily focused on helping your existing customers experience live TV (programs scheduled in a 24/7 linear feed) in a content forward way. It is based on the following Android documentation: Develop a TV input service.

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 Features on Fire TV

After completing this integration, the following features will be available across all Fire TV devices when a customer installs and authenticates your application. (Note that the "Live" tab is not available in all marketplaces).

Linear content tiles on the Home tab display the current programming information for each linear feed:

Linear content tiles on the Home tab

Linear content tiles on the Live tab show the current programming information:

Merchandising opportunities

Linear content tiles on the Live tab show the current programming information:

Linear content tiles on the Live tab

Integrated channel guide with 14 days of programming appears for each channel:

Integrated channel guide showing 14 days

Users can search for station and programming information for the next 14 days:

Search for station/programming information

Alexa support for "Tune to <channel_name>" is available:

Tune to channel name

Users can favorite and manage channels within the browse experiences:

Favorite and manage channels

All browse, search, and voice ingress points listed above have the option to have playback handled in the native live TV application or initiated via deeplinks.

Integration Requirements

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.

No Gracenote IDs?

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 Android Sample TV Input Application 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.

Parental Controls

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.

Best Practices

The following are a set of product and implementation guidelines that provide your customers the best live TV experience on Fire TV:

  • Provide a friction-free sign-up to encourage trial where applicable. Examples include reducing registration forms on the application or utilizing a phone number to sign up.
  • Support live channel preview in browse to drive engagement
  • Use a transparent, monochrome logo for each TvContract.Channels.Logo in your channel lineup.
  • Optimize deep-link flow to begin full-screen playback in less than 2.5 seconds
  • Leverage Gracenote channel IDs where applicable to simplify integration
  • Focus on metadata loading performance over having full schedule availability
  • Use JobScheduler or WorkManager to periodically check and ensure entitlements are always accurate. This will ensure your channels in the browse and search experiences are in sync with the reality of entitled channels at all times even if your application does not enter the foreground.
  • Update your entitled channel list in place is preferred to removing and re-adding all channels in the case where the entitled channel list has changed slightly.
  • Provide a displayable channel name for COLUMN_DISPLAY_NAME column since this may be used as a fallback in the UI. Fire TV displays up to 16 characters.

Whitelisting Package

There is a package whitelist that determines which applications are capable of surfacing their channels in the Fire TV browse and search experiences. You will need to share a list of Device Serial Numbers (DSN) with your Amazon counterpart to ensure you are able to integrate and validate the features outlined above on your device prior to launching.

Provider Attribution

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.

No Gracenote IDs?

When you 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.

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 (ex. "On Now" row, Channel Guide) once a customer performs one of the following: (1) open and sign-into the application or (2) access the application’s setting page when I access Settings –> Live TV –> Live TV Sources –> <Application Name>.
  • If a customer’s membership expires (i.e., turns to unentitled), 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 shall be removed from the Fire TV UI when the application is uninstalled or if those channels become unentitled.

Browse and Playback Experience

  • A rich metadata experience will be available when focused on a channel. In the 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 matching or pushed as part of the TV contract.
  • When a customer focuses on a channel in the “On Now” row, a customer will be able to 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 eventually return to the Fire TV UI.
  • A PIN prompt will show prior to playback if PCON is enabled. Live channel preview must be disabled if PCON is enabled.
  • Audio of live playback must be muted if Alexa is accessed; video is expected to continue.
  • (Optional) 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 whitelist specific accounts to review and certify the integrated experience before going to production.
  • Only entitled channels are added Fire TV UI in the marketplaces both parties have agreed to launch. Subsequent launches in new marketplaces will constitute as a new certification review and require whitelisting.
  • 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.

Code Samples

The following code example shows how to include a Gracenote ID and deeplink into the TV database.

/**
 * Variable to store the type of external ID, which is used for the matching service metadata. Valid types are
 * defined below as constants with prefix "EXTERNAL_ID_TYPE_"
 * Null or invalid data will result in failed service
 * match of metadata
 */
private final static String EXTERNAL_ID_TYPE = "externalIdType";

/**
 * Variable to store the value of external ID, which is used for the matching service metadata.
 * Null or invalid data will result in failed service match of metadata
 */
private final static String EXTERNAL_ID_VALUE = "externalIdValue";

/**
 * Uri for deep link of playback into external player.
 * Null or invalid data will result in default as integrated with Gordon player
 */
private final static String PLAYBACK_DEEP_LINK_URI = "playbackDeepLinkUri";

// Contract for list of known External ID Type Constants
private final static String EXTERNAL_ID_TYPE_GRACENOTE_ONTV = "gracenote_ontv"; // gracenote ontv id

// Contract for playback deep link uri
// Use Intent.URI_INTENT_SCHEME to create uri from intent and to covert back to original intent
Intent playbackDeepLinkIntent; // Created by your app
String playbackDeepLinkUri = playbackDeepLinkIntent.toUri(Intent.URI_INTENT_SCHEME);

// Construct BLOB
ContentValues values = new ContentValues();  // store all the channel data
ContentResolver resolver = context.getContentResolver();
values.put(TvContract.Channels.COLUMN_DISPLAY_NAME, "#Actual display name#");
values.put(TvContract.Channels.COLUMN_INPUT_ID, "#Actual input id#");
try {
    String jsonString = new JSONObject()
                  .put(EXTERNAL_ID_TYPE, "#Actual Id Type#")
                  .put(EXTERNAL_ID_VALUE, "#Actual Id Value#")
                  .put(PLAYBACK_DEEP_LINK_URI, playbackDeepLinkUri).toString();

    values.put(TvContract.Channels.COLUMN_INTERNAL_PROVIDER_DATA, jsonString.getBytes());
} catch (JSONException e) {
    Log.e(TAG, "Error when adding data to blob " + e);
}

Uri uri = resolver.insert(TvContract.Channels.CONTENT_URI, values);

Honoring Parental Controls

The following code example demonstrates how to listen to parental controls for live preview or native full screen playback.

private TvContentRating mBlockedRating = null;

    @Override
    public boolean onTune(final Uri channelUri) {
        ...
        if (mTvInputManager.isParentalControlsEnabled()) {
            // ensure playback is not audible or visible on the Surface
            mBlockedRating = <content_rating>;
            // 1. Triggers PIN prompt to user when in fullscreen playback
            // 2. Ensures the program image does not flip to the playback Surface
            //    when browsing the On Now row.
            notifyContentBlocked(mBlockedRating);
        } else {
            // playback should start
            notifyContentAllowed();
        }
        ...
    }

    @Override
    public void onUnblockContent(final TvContentRating unblockedRating) {
        // the user successfully entered their PIN to unblock content for the
        // provided rating
        if (unblockedRating.unblockContent(mBlockedRating)) {
            // playback should start
            notifyContentAllowed();
        }
    }