The TV Input inserts channel and program metadata into the TV Input Framework (TIF) database. Fire TV uses this data to display your service’s live content in the Fire TV Live sections. TV Input channel and program metadata must be up-to-date and match the data inside the app. Steps 3 and 4 demonstrate how to insert this data and keep it up-to-date.
Add permissions to the manifest
AndroidManifest.xml before your app can interact with the TIF database.
Insert channel metadata into Android’s TV database
There are two ways you can insert a basic channel into Android’s TV Database. You can insert the channel to a class or an object.First approach: SetupActivity class
- Java
- Kotlin
Second approach: Channel object provided in the AndroidX library
- Java
- Kotlin
onCreate() method in your SetupActivity (replace the existing code).
- Java
- Kotlin
| Activity | Required? | Input | Notes |
|---|---|---|---|
COLUMN_INPUT_ID | Yes | The full class path to the TvInputService | Example: TvInputService is in the main app package, then the full class path is <app package>/<relative path to your TvInputService>. If TvInputService is in a separate package, then the input ID is <app package>/<full separate package + path to TvInputService>. |
TvContract.Channels.CONTENT_URI | Yes | This is the URI pointing to the channel table in Android’s TV Database. | |
ContentResolver.bulkInsert() or ContentResolver.applyBatch() | Yes, in production code | One of these ensures all channel insertions happen with one database operation. |
Insert Amazon catalog station ID
Skip this section if you aren’t using an Amazon catalog format. Amazon’s current catalog format is Enhanced Metadata Bridge for Entertainment Resources (EMBER). However, Amazon still supports the legacy Catalog Data Format (CDF) for existing integrations. Amazon’s linear catalog ingestion system, the underlying technical integration, lets you upload your linear channel schedules and programming metadata directly to the Amazon Fire TV catalog. If you are interested in integrating with EMBER, contact your Amazon representative for more information. Here is an example of inserting the unique catalog station ID into a JSON object using Amazon’s contract keys to indicate both the type and ID. You can place this inside the insert channels function inSetupActivity.
- Java
- Kotlin
station-001, station-002, or station-003 with the test_cdf2 as provider namespace.
Insert Gracenote ID
If you aren’t using Gracenote, skip this section. Gracenote is a TV catalog provider that integrates with Fire TV to provide channel and program metadata from the cloud. If your content is integrated with Gracenote, you may provide unique IDs which Fire TV uses to gather this metadata. If you’re interested in integrating with Gracenote, contact your Amazon representative for more information. Here is an example of inserting the unique channel Gracenote ID into a JSON object using Amazon’s contract keys to indicate both the type and ID. You can place this inside the insert channels function inSetupActivity.
- Java
- Kotlin
- If you have another type of Gracenote ID, check to see which kind. If you are uncertain about this, contact your Amazon representative.
-
If you plan to use Gracenote, but don’t have your Gracenote ID yet, you can temporarily use the following for development purposes. In the US/UK/DE, you can use these sample IDs: 10171 (Disney Channel), 10240 (HBO), and 12131 (Cartoon Network), with the gracenote_ontv
externalIdType. For all other marketplaces, you can use sample IDGN9BBXQSECYVNGW(HBO) with the gracenote_gvdexternalIdType.
Insert deep link
Insert the deep link into a JSON object using Amazon’s contract key stringplaybackDeepLinkUri.
- Java
- Kotlin
Checkpoint: Display one channel on Fire TV’s UI
Use the following steps to verify your setup.- Build and install your APK on a Fire TV.
- Navigate to Settings > Live TV > Sync Sources and select the source.
- Navigate to Home > On Now row. The inserted channel should appear as one of the cards (a box with content, sometimes called a tile). For integrations not using Gracenote or an Amazon catalog format, you see a gray tile with a channel name. If there are many channels on your device from other sources, your channel might not appear because there is a limit.
- Navigate to Live TV > Channel Guide, open the Options menu (3 lines) > Filter Channels > your input name. The inserted channel should appear on the screen as a row.
- Navigate to Settings > Live TV > Manage Channels. Your input name (from the job service XML file) should appear under the list and have the inserted channel assigned to it.
- If using deep link, click the channel card in the On Now row. The app should launch and display the expected channel.
Troubleshooting
This section contains steps to troubleshoot issues you might encounter. The channel is not showing up in the On Now row or Channel Guide.- Refer to the Checkpoint to verify it’s added to the allow list.
- Verify that the input ID of that channel equals the full class path to TvInputService.
- Verify that the debug APKs and the production APKs have the same package names.
-
Verify that the channel is correctly inserted into TIF.
- Create a hard-code query for channel information right after the insert to make sure the channel is in the database.
-
Verify that Amazon picks up the channel correctly.
-
Before inserting the channel, view ADB logs:
For Mac / Linux
adb logcat | grep StationSyncFor Windowsadb logcat | findstr StationSync - After you insert the channel, you should be able to see logs similar to what you find below. Added means Amazon is recognizing a new channel in Android’s TV Database.
-
Before inserting the channel, view ADB logs:
For Mac / Linux
- This is expected behavior if a channel isn’t integrated with Gracenote or an Amazon catalog format. If it is integrated with these systems, see the following.
- Make sure you know if your feed is for onTV, GVD, or an Amazon catalog format and define it correctly where you build your channel metadata. Amazon supports onTV for certain marketplaces. If there is a mismatch between what Amazon supports and what type of Gracenote ID or Amazon catalog ID you have, contact your Amazon representative. They can work with Gracenote to correct the issue, or switch to TIF.
- Verify the value of the Gracenote ID or Amazon catalog ID. onTV utilizes numerical values only, while GVD and Amazon catalog IDs are alphanumeric.

