Vega Live TV Integration & Sanity Testing

Vega Open Beta Knowledge Base
1

:exclamation: At this time, Live TV integration is available to select partners only.

This article outlines the essential practices and commands required for testing Live TV integration on Vega, along with a comprehensive set of mandatory test cases utilized by Amazon for certification purposes. This knowledge base serves as a complementary resource to the Vega Live TV developer documentation.

Important Note: While this article provides testing guidelines, always refer to the official Vega Live TV developer documentation for the most up-to-date information and requirements, as certification standards may evolve over time.

Prerequisites

  1. Package ID - Please ensure that you are using the same package ID for Vega app as your existing Fire OS (FOS) app package id (e.g. appname.example.com). Amazon uses your same package ID to configure Live TV services across FOS and Vega. For instructions on how to change your package ID, go here.
  2. Implement the Live TV integration

Test Scenarios and Success Criteria

The following test cases are required for the Live TV integration. Before you submit your app for Live TV certification, please run these test cases and provide results to your Amazon contact. It is essential that you verify these test cases in advance, to reduce back-and-forth during the certification process. You can mark “Not Applicable” for test cases which are not relevant to your app, providing appropriate justifications in the comment section.

Feature Description Criteria Steps
Entitlement/Initial Sync Channel sync on Live experience screens after Installation and Sign-in (if applicable) All Live experience screens must be loaded with channel details within 1 min 1. Install app
2. Sign in (if required)
3. Verify access to:
- EPG
- Partner Row
- Live TV elements

Success = All elements load & display correctly
Entitlement Uninstalling the provider must remove the app/channels presence from EPG, Home tab, Sync Sources, Browse rows, Live TV sources, Recents, Manage Channels App and channels presence must be removed from all the live experience screens within 1 min 1. Uninstall app
2. Verify: - Channels removed from EPG
- Live TV elements cleared
- Partner Row content removed

Success = All app-related content completely removed from Fire TV UI
Entitlement Logging out of the app (if the app requires sign-in) must remove the app/channels presence from EPG, Home tab, Sync Sources, Browse rows, Live TV sources, Recents, Manage Channels App and channels presence must be removed from all the live experience screens within 1 min 1. Logout from app
2. Verify:
- Channels cleared from EPG
- Live TV elements removed
- Partner Row content gone

Success = All user-specific content removed from Fire TV UI while app remains installed
Entitlement While upgrading from one type of subscription to another OR from free to entitled, respective channels must be populated in all live experience screens New set of Channels must be populated within 1 min 1. Upgrade subscription:
- Current tier → Higher tier
- (e.g., Premium → Premium+)

2. Verify:
- New tier channels appear in EPG
- Additional content visible
- UI updates reflect new tier access.

Success = All higher tier content accessible immediately after upgrade
Playback Select tile to Playback from On Now Row/Live tab/EPG/Search result Fullscreen Playback must start within 2-5 secs for warm and 5-7 for cold start for 100% of the channels

Blocker - If playback is not initiated within the SLA mentioned
Blocker - If playback from live ingress getting stuck when switching channels consistently		 1. Launch playback from:
- EPG grid
- Partner row
- On Now row
2. Verify:
- Channel launches successfully
- Playback starts
- Stream quality is good

Success = Smooth playback from all entry points
UX Tiles in all Live TV UI screens must have the program image and no grey tile 100% of the Tiles must have program image if the program information is available

Blocker - If >75% of the tiles are showing grey tiles		 1. Check channel tile images in:
- EPG grid
- Partner row
- On Now row

2. Verify:
- Images load properly
- No broken/missing thumbnails
- Correct images for channels

Success = All channel tiles display appropriate images
UX/Channel Sort Order 1. Channel Name must match with the requirement 2. Channel sort order and logo in EPG (on the left most column)/On Now Row/Live tab/Manage channels must match with the requirement 3. Channel count must match with the list provided to the Amazon Contact 1. Channel name must reflect the name in the Channel list Quip. 100% of the channels must have proper logo and reflect the channel order as per the requirement

2. Custom Order - Reflect Channel List Quip Default Order - A-Z order or Channel numbering as per the requirement

3. Channel count is matching with the requirement in On Now Row, Live tab provider row, EPG and Manage channels		 1. Check channel sequence in:
- EPG grid
- Partner row
- On Now row

2. Verify:
- Matches provided channel order
- No misplaced channels
- Consistent across all UI elements

Success = Channel order matches specified sequence in docs
UX Provider name displayed must be as expected in all available live experience screens Provider names must match display name submitted with partner in-take channel list and must be consistent across all live experience screens 1. Check provider name in:
- EPG grid
- Partner row
- On Now row

2. Verify:
- Consistent branding
- Correct spelling
- Same name everywhere

Success = Provider name uniformly displayed as specified.
Metadata Validate metadata, and progress bar on the tile Home Recent Home On Now Row Live tab Recent EPG Live tab provider row Metadata must be loaded in all live experience screens within 1 min after initial sync
Metadata must show within 1 sec of tile focus for >=95% of the contents
1. Program name
2. Start and end time
3. Content rating (if available)
4. Closed captions (if available)
5. Video quality (if available)
6. Up Next (for GN)
7. Short description

Blocker - If the impact is on more than 5% of the contents		 1. Focus on channel tile in:
- EPG grid
- Partner row
- On Now row

2. Verify preview shows:
- Program title
- Time (start/end)
- Rating (if applicable)
- CC icon (if applicable)
- Video quality (if applicable)
- Up Next info (GN only)
- Program description

Success = All metadata elements present and accurate
Sync Source Channel line up should be updated by triggering the Sync Sources. Launch Sync Source Screen by - Settings > Live TV > Sync Sources Your sync sources screen launches and has Method 1: Via Settings Menu
1. Navigate to: Settings > Live TV > Sync Sources
2. Verify the following screens appear in sequence:
- “Updating Channel Info” screen
- “Channel Sync Complete” message
- Auto-return to previous Fire TV UI screen

Method 2: Via Terminal (if Method 1 fails)
Step 1: Log Capture
Terminal 1: Start capturing EPG/KTF logs vda shell journalctl -f | grep -i "epg:|ktf:|ktf.|epgSyncTask|EpgSync"
Step 2: Trigger Sync
Terminal 2: Execute sync source command vlcm launch-app pkg://<package-id>.sync_source

Expected Log Sequence
Verify these messages appear in order:
>>INFO ktf:start bulk inserting channels
>>INFO ktf:bulk insert channels successfully
>>INFO ktf:channel lineup provider commit version: [nnn]
>>INFO ktf:[nnnn] of the [nnnn] requested channels have been added

Success = All channels are updated and logs show the complete sequence using method 1.
Exit To verify if pressing back button takes the customer back to the point of ingress such as EPG, Live Partner row, On Row The back button should always bring the customer back to the ingress point and not to the App’s home page. 1. EPG Exit Test
From Live Tab:
1. Live Tab → EPG → Play channel
2. Press Back
- Verify: Returns to EPG tile

From Home Tab:
1. Home Tab → EPG → Play channel
2. Press Back
- Verify: Returns to EPG tile

2. Partner Row Exit Test
1. Live Tab → Partner Row → Play channel
2. Press Back
- Verify: Returns to Partner Row tile

3. On Now Row Exit Test
1. Home Tab → On Now Row → Play channel
2. Press Back
- Verify: Returns to On Now Row tile

Note: Some apps may exit to home first before returning to previous location

Success = Back button returns to correct ingress point in all scenarios
Parental Controls (PCON) The user creates a PIN when enabling parental controls the first time. Afterwards, when another user encounters a restricted video, the PIN prompt appears. That user must enter the correct PIN in order to access that content. The content restriction level is set by the user in Settings > Preferences > Parental Controls > Viewing Restrictions. To verify if PCON works, the customer should be prompted to enter PCON PIN when starting playback of Live Channel from Live row or any other ingress point. The PCON Prompt should be seen when customer starts playback from Live Row or any other ingress point.

Please refer to developer doc for sample CX - Vega Parental Controls		 1. FTV Native Player
1. Launch channel from:
- Partner Row
- EPG
- On Now Row
2. Verify:
- PCON PIN prompt shows
- Uses FTV native dialog
- Playback starts after PIN

2. In-App Player
1. Launch channel (same entry points)
2. Verify:
- PCON PIN prompt shows
- Uses app’s PIN dialog
- Playback starts after PIN

Success = PIN verification required before playback in both scenarios

Common Issues and Troubleshooting

Common Issues:

  1. If the app is failing to launch or integrate properly, please verify the package ID matches exactly with the FOS app package ID.
  2. If you are unable to access content or features, please work with your Amazon contact to confirm the DSN is properly allowlisted. Check the user credentials if applicable.
  3. If there is missing or incorrect program information, validate the EPG data format. Verify the EPG sync task logs using this command:
vda shell journalctl -f | grep -i "epg:\|ktf:\|ktf.\|epgSyncTask\|EpgSync"
  1. If the PCON restrictions are not working as expected, verify the rating implementation. Check the PIN verification flow. It should match with your FOS implementation.

General Troubleshooting Steps and Capturing Logs:

  1. Check logs for specific error messages. Restart the application / device.
  2. Open two terminals before installing and running the application.
  3. In the first terminal, type this command to capture the grep epg sync task related logs:
vda shell journalctl -f | grep -i "epg:\|ktf:\|ktf.\|epgSyncTask\|EpgSync"

  1. In the second terminal, install and run the app (you can do this from VS Code as well):

    1. Push the .vpgk to the device: vda push /path/to/MyFireTVApp_armv7.vpkg /tmp/
    2. Install the .vpgk: vda shell vpm install /tmp/MyFireTVApp_armv7.vpkg

  2. Verify the logs in the first terminal for successful channel insertion.

  3. If Sync Source fails via UI, verify implementation by running:

vda shell vlcm launch-app orpheus://[MyFireTVApp_package_Id].sync_source
  1. Example to capture logs directly to file:
vda shell journalctl -f | tee [FileName]_[Date].log
  1. Open a bug report if the issue persists.

Last updated: Mar 10, 2026