Vega Target Navigator Provider

The Vega Target Navigator API “targets” screens or sections within an app where users interact with input modes such as Home, Settings, Profile, or Search. Apps implementing the Target Navigator provider interface can do the following.

Query available targets — Discover which screens or sections the app offers for navigation.
Query the current target — Determine which screen or section the user is viewing.
Navigate to a target — Navigate the app to a specific screen or section.

The Target Navigator provider API has three key components.

handleGetCurrentTarget — A callback that returns active app targets.
handleGetAvailableTargets — A callback that returns supported navigation targets.
handleNavigateTargetRequest — A callback invoked when the system requests specific target navigation.

Providers must proactively report state changes by using the following methods.

updateCurrentTarget — Notify the system when the current target changes.
updateAvailableTargets — Notify the system when the list of available targets changes.

Vega Target Navigator Prerequisites

Before using this API, update your app manifest to declare your intention to use the Vega Target Navigator API. When modifying the manifest entries, replace com.amazondeveloper.media.sample with your app package ID. Your app must be properly configured to interact with the Vega Target Navigator API.

schema-version = 1

[package]
title = "<Your app title>"
id = "com.amazondeveloper.media.sample"

[components]

[[components.interactive]]
id = "com.amazondeveloper.media.sample.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
# The category "com.amazon.category.kepler.media" is only necessary for the primary component,
# which is identified in the [[extras]] section of the manifest using the "component-id" value.
categories = ["com.amazon.category.main", "com.amazon.category.kepler.media"]

[processes]

[[processes.group]]
component-ids = ["com.amazondeveloper.media.sample.main"]

[offers]

[[offers.interaction]]
id = "com.amazondeveloper.media.sample.main"

[[offers.interaction.message]]
uri = "pkg://com.amazondeveloper.media.sample.main"
sender-privileges = ["*"]
receiver-privileges = ["self"]

[[offers.module]]
id = "/com.amazondeveloper.media.sample.module@ISomeUri1"
includes-messages = ["pkg://com.amazondeveloper.media.sample.main"]

[[extras]]
key = "interface.provider"
component-id = "com.amazondeveloper.media.sample.main"

[extras.value.application]

# Add the Target Navigator interface
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.ITargetNavigator"

Step 1: Install and set up Vega Target Navigator

To use the Vega Target Navigator API, update your package.json file with the following dependency:

"dependencies": {
  "@amazon-devices/vega-target-navigator-provider": "~1.0.10"
}

Step 2: Define your available targets

A TargetInfo object represents each target with the following fields:

identifier (number, required) — A unique numeric ID for a target within your app.
name (string, optional) — A human-readable name for the target.
standardId (StandardTargetIdentifier1, optional) — A standard identifier that maps to well-known destinations, enabling the system to understand the target’s purpose.

The available standard target identifiers are:

StandardTargetIdentifier1	Value	Description
HOME	0	App home screen
LOGIN	1	Login screen
PROFILE	2	User profile
SETTINGS	3	App settings
PRIVACY	4	Privacy settings
HELP	5	Help screen
ABOUT	6	About screen
TERMS	7	Terms of service
SEARCH	8	Search screen
RECOMMENDATIONS	9	Recommendations
TRENDING	10	Trending content
DOWNLOADS	11	Downloads
HISTORY	12	Watch history

You can define your targets as a map keyed by identifier:

import {
  TargetNavigatorProvider,
  TargetNavigatorHandler,
  TargetInfo,
  StandardTargetIdentifier1,
} from '@amazon-devices/vega-target-navigator-provider';
...
const availableTargets: { [key: number]: TargetInfo } = {
  0: { identifier: 0, name: 'Home', standardId: StandardTargetIdentifier1.HOME },
  1: { identifier: 1, name: 'Profile', standardId: StandardTargetIdentifier1.PROFILE },
  2: { identifier: 2, name: 'Settings', standardId: StandardTargetIdentifier1.SETTINGS },
};

The Target Navigator Interface also supports custom targets without a standardId.

const customTarget: TargetInfo = { identifier: 100, name: 'My Custom Screen' };

Step 3: Implement the Target Navigator handler

Create a TargetNavigatorHandler object that implements three callback methods.

const targetNavigatorHandler: TargetNavigatorHandler = {
  handleGetCurrentTarget: (): Promise<TargetInfo[]> => {
    return Promise.resolve([currentTarget]);
  },

  handleGetAvailableTargets: (): Promise<TargetInfo[]> => {
    return Promise.resolve(Object.values(availableTargets));
  },

  handleNavigateTargetRequest: (target: TargetInfo): Promise<string> => {
    // Prefer matching by standardId if provided, fall back to identifier
    let matchedTarget: TargetInfo | undefined;
    if (target.standardId !== undefined) {
      matchedTarget = Object.values(availableTargets).find(
        (candidate) => candidate.standardId === target.standardId
      );
    }
    if (matchedTarget === undefined) {
      matchedTarget = availableTargets[target.identifier];
    }
    if (matchedTarget === undefined) {
      return Promise.reject(new Error(`Target not found`));
    }
    currentTarget = matchedTarget;
    TargetNavigatorProvider.updateCurrentTarget(currentTarget);
    return Promise.resolve('Success');
  },
};

Handler method details

Method	Returns	Description
`handleGetCurrentTarget()`	`Promise<TargetInfo[]>`	Return the currently active target(s). Return an empty array if none.
`handleGetAvailableTargets()`	`Promise<TargetInfo[]>`	Return all navigable targets. Must not exceed 256 elements.
`handleNavigateTargetRequest(target)`	`Promise<string>`	Navigate to the target. Resolve with status string on success, reject with `Error` on failure.

Step 4: Register the handler

Register the handler using IComponentInstance from useKeplerAppStateManager(). Don’t do this on startup before calling any update methods.

const componentInstance = useKeplerAppStateManager().getComponentInstance();

TargetNavigatorProvider.registerTargetNavigatorHandler(
  targetNavigatorHandler,
  componentInstance
);

Step 5: Report target state changes

After registering the handler, notify the system of the current state. Call both updateCurrentTarget and updateAvailableTargets on startup, and again if the state changes.

Update current target

Call app initialization whenever the user navigates to a different screen:

TargetNavigatorProvider.updateCurrentTarget(availableTargets[2]);

Pass undefined to indicate no current target, such as in a transitional state.

TargetNavigatorProvider.updateCurrentTarget(undefined);

Update available targets

Update targets when the any navigable destinations change, such as when the user logs in.

TargetNavigatorProvider.updateAvailableTargets(Object.values(availableTargets));

Troubleshooting Vega Target Navigator

Issue	Resolution
Handler not receiving requests	Verify manifest `interface_name` is exactly `"com.amazon.kepler.media.ITargetNavigator"` and `component-id` matches your interactive component.
Target not found errors	Make sure the available target list is kept up to date using `updateAvailableTargets()`.
Handler registered too late	Register in `useEffect` on mount before any requests arrive.

API Reference

Classes

TargetNavigatorProvider — TargetNavigatorProvider

Interfaces

TargetInfo — Represents a target of navigation.
TargetNavigatorHandler — The interface implemented by a target navigator server to handle requests.

Enumerations

StandardTargetIdentifier1 — An enum of standard navigation targets.

​Vega Target Navigator Prerequisites

​Step 1: Install and set up Vega Target Navigator

​Step 2: Define your available targets

​Step 3: Implement the Target Navigator handler

​Handler method details

​Step 4: Register the handler

​Step 5: Report target state changes

​Update current target

​Update available targets

​Troubleshooting Vega Target Navigator

​API Reference

​Classes

​Interfaces

​Enumerations

​Related topics