Sync Source Screen

Fire TV provides mechanisms for customers to 'force' refresh a Live TV app's entitlements, channel metadata, and programs to obtain the latest information, which will be seen on the Live TV Settings screen.

• Integration steps
  • Step 1: Include the necessary package dependencies in your app
  • Step 2: Update your manifest file
  • Step 3: Create your screen
  • Step 4: Tell the system about your screen’s entry point.
• Expected behavior of the sync source screen
• Related topics

Here’s an example of a splash screen while the sync is in progress.

Follow the steps below to support this feature in your app.

Integration steps

Step 1: Include the necessary package dependencies in your app

Add the following dependencies in your package.json file.

  "dependencies": {
    "@amazon-devices/kepler-epg-provider": "^1.9.0",
  }

• The kepler-epg-provider package provides APIs for pushing EPG data (channel entitlements, metadata, and programs) to the system.

Step 2: Update your manifest file

Update your manifest.toml file to include a sync source interactive component. The following is an example, showing part of a manifest.toml file for a Vega Sample App.

## Declare your app's sync source component 
[[components.interactive]]
id = "<packageId>.sync_source"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"

## Declare your app's capability for sync source feature
[offers]
[[offers.message-target]]
## Use the same component ID defined earlier for sync source handling.
uses-component = "<packageId>.sync_source"
## Live TV settings uses this message to launch your sync source screen.
uris = ["livetv://sync_source"]

Step 3: Create your screen

Add the following files to your app package and define your business logic to show a splash screen and push the latest EPG data to the system.

Create your app’s sync sources screen by creating a EpgSyncSource.tsx file in your src folder with the following content.

import {
  ingestChannelLineup,
  ingestProgramLineup,
} from './src/EpgSyncTask';

const EpgSyncSource = () => {

    //Callback passed to channel and program ingestion for updating progress bar
    const progressCallback = React.useCallback((progress: number) => {
        //Update progress bar
    }, []);

    const ingestLineup = React.useCallback(async () => {
        try {
            //Ingest channel and program lineup
            await ingestChannelLineup(progressCallback);
            await ingestProgramLineup(progressCallback);

            //Show sync complete message
        } catch (error){
            //Show sync failed message
        }
        //Wait 3 seconds and exit
        await new Promise(r => setTimeout(r, 3000));
        BackHandler.exitApp();
    }, [progressCallback]);

    //When screen is launched:
    useEffect(() => {
        //Show login screen if needed for channel entitlement
        if(isCustomerLoggedin === false) {
            showLoginScreen();
         }
         //Begin sync of customer’s Live TV data
        ingestLineup();
    }, [ingestLineup]);

    return (
        <View style={styles.container}>
            //Splash screen showing message to customer with status and progress indicator
        </View>
    );
 };

export default EpgSyncSource;

It’s best to reuse functions for providing channels and programs from the EpgSyncTask. If you don’t plan to reuse functions, see Vega EPG Provider for details on EPG ingestion.

Step 4: Tell the system about your screen’s entry point.

Update your index.js file to register the sync source component using the component ID defined in your manifest.toml file and the screen defined in SyncSource.tsx. Below is the code for a Vega Sample App.

import { AppRegistry } from 'react-native';
import App from './src/App';
import EpgSyncSource from './src/EpgSyncSource';

AppRegistry.registerComponent("<packageId>.main", () => App);
AppRegistry.registerComponent("<packageId>.sync_source", () => EpgSyncSource);

Your app should now be correctly structured with a sync source screen. Next, complete the logic for your screen and sync.

Expected behavior of the sync source screen

Your app’s sync source screen needs to do the following when launched:

1. If your app requires customers to be logged in for channel entitlement and they are not currently logged in, forward the customer to your login screen.
2. Once the customer is logged in, begin a sync of the customer’s channel entitlements, metadata, and programs using Vega EPG Provider to push the data to the system.
   1. This sync should be started immediately and occur as a background task.
   2. It’s best to reuse the same code for EPG ingestion from your EpgSyncTask.
3. Display a splash screen for the user indicating that a sync is in progress.
   1. It should have a progress bar as a best practice, or a loading animation if you can’t implement a progress bar.
   2. This screen should display a warning message that the customer should not leave the screen or the sync will fail.
4. Once the sync is complete, update the screen to notify the user that the sync is finished.
5. Exit the screen within a few seconds of the sync completion.

Related topics

• Vega Live TV Data Type Reference
• Vega Live TV Issues
• Vega Live TV API Overview

Last updated: Sep 30, 2025