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
);
useEffect on mount. The handler must be registered before calling updateCurrentTarget or updateAvailableTargets, since those calls will fail if no handler is set.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.
Related topics
- Develop for Vega
- Vega Matter Casting Integration
- Content Launcher Integration Guide
- Get Started with Vega Media Controls
- Content Launcher and Account Login Testing
Last updated: Jul 15, 2026
