Vega Channel Integration

Here's what you need to know to integrate Vega Channel into your app for Fire TV. The Vega Channel interface provides modality-agnostic APIs for playing your linear TV content. This can be done using a remote (your Fire TV EPG/Launcher), touch, voice (such as saying to an Alexa enabled device, "Alexa, tune to…."), or casting.

Prerequisites

• Access to the source code of your app for Fire TV.
• A Fire TV device that supports this integration. Check with your Amazon contact for a list of device types currently supported.
• Integration with the Vega Electronic Programming Guide (EPG) Provider.

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-channel": "^1.1.0",
  }

• The kepler-channel package contains APIs for the Vega Channel interface for you to implement in your app.

Step 2: Update your manifest file

Update your manifest.toml file to include Vega Channel support. See the following Vega Sample App.

[components]
## Define your app's interactive component (if it doesn't already exist)
[[components.interactive]]
id = "<packageId>.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
categories = ["com.amazon.category.main", "com.amazon.category.kepler.media"]

[[extras]]
## `interface.provider` designates a component 
## that provides implementation of certain interfaces
key = "interface.provider"
## Declares the component that provides the implementation of the interfaces.
## This component must be defined under [[components.interactive]] and includes
## "com.amazon.category.kepler.media" in its categories.
component-id="<packageId>.main"

[extras.value.application]
## Declare support for Vega Channel
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IChannelServer"
features = ["ChannelList"]

Details about the 2 categories added for the main interactive component:

• com.amazon.category.main declares the component as the default interactive component for the application package.
• com.amazon.category.kepler.media declares the component to be targeted for Vega Media operations.

For more information, see the Manifest [components] Section.

The manifest file declares the support of the com.amazon.kepler.media.IChannelServer interface. The component <packageId>.main defined for "interface.provider" handles all the channel command callbacks. For more information, see steps 3 and 4.

Correct interface definition example

Each interface definition in the manifest must be separate and self-contained. Do not mix attributes from different interfaces. Here is an example of the correct way to define multiple interfaces.

[extras.value.application]
## IChannelServer Interface
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IChannelServer"
features = ["ChannelList"]

## IContentLauncherServer interface
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IContentLauncherServer"
attribute_options = ["partner-id"]
[extras.value.application.interface.static_values]
partner-id = "<Your partner id>"

Incorrect interface definition example

And here is an incorrect way to do this. Do not do it this way.

Copy code Copied to clipboard.

[extras.value.application]

[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IContentLauncherServer"
attribute_options = ["partner-id"]

[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IChannelServer"
features = ["ChannelList"]

[extras.value.application.interface.static_values]
partner-id = "<Your partner id>"

Step 3: Create the handler object for the Vega Channel interfaces

Create a handler which contains the implementation of the Vega Channel interface:

import {
  ChannelServerComponent2,
  ChangeChannelStatus,
  IChannelHandler,
  IChangeChannelResponse,
  OperationError,
} from '@amazon-devices/kepler-channel';

/**
 * The handler that implements the Vega Channel interface
 */
const channelTunerHandler: IChannelHandler = {
  async handleChangeChannel(
    channelIdentifier: string,
  ): Promise<IChangeChannelResponse> {

    /**
     * The value of ${channelIdentifier} here will contain data from the
     * ChannelDescriptor.identifier field from the Vega EPG Provider
     * if it was supplied during EPG Ingestion.
     */

    // Add your business logic to tune to ${channelIdentifier} here.

    const response = ChannelServerComponent2.makeChannelResponseBuilder()
      .status(ChangeChannelStatus.SUCCESS)
      .build();
    return Promise.resolve(response);

  },

    /**
     * handleChangeChannelByNumber should not be used, implement and use handleChangeChannel instead
     */
  async handleChangeChannelByNumber(
    majorNumber: number,
    minorNumber: number,
  ): Promise<IChangeChannelResponse> {
    throw new OperationError(
      'handleChangeChannelByNumber should not be used, implement and use handleChangeChannel instead',
    );
  },

  async handleSkipChannel(
    channelCount: number,
  ): Promise<IChangeChannelResponse> {

    // Add your business logic to handle skip channel

    const response = ChannelServerComponent2.makeChannelResponseBuilder()
      .status(ChangeChannelStatus.SUCCESS)
      .build();
    return Promise.resolve(response);
  },
};

Step 4: Supply your handler object to ChannelServer so it can be invoked

Add code similar to the following in your interactive component:

// Use the latest ChannelServerComponent2 from the library
import { ChannelServerComponent2 } from '@amazon-devices/kepler-channel';
import {
  IComponentInstance,
  IKeplerAppStateManager,
  useKeplerAppStateManager,
} from '@amazon-devices/react-native-kepler';

const keplerAppStateManager: IKeplerAppStateManager = useKeplerAppStateManager();
// Get the component instance
const componentInstance: IComponentInstance = keplerAppStateManager.getComponentInstance();

React.useEffect(() => {
 // Provide a handler for the given component instance to the Channel server.
 ChannelServerComponent2.getOrMakeServer().setHandlerForComponent(channelTunerHandler, componentInstance);
 }, []);

That’s it! You have completed the Vega Channel integration and it should be ready to receive commands.

Related topics

• Sync Source Screen
• Vega Live TV API Overview
• Vega Live TV Issues

Last updated: Sep 30, 2025