Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
Ring
AWS
ドキュメント
Support
Contact Us
My Cases

Console

as

開発
設計と開発
公開
リファレンス
サポート

Vegaターゲットナビゲータープロバイダー

Vegaターゲットナビゲータープロバイダー

VegaターゲットナビゲーターAPIは、ユーザーがホーム、設定、プロフィール、検索などの入力モードで操作するアプリ内の画面やセクションを「ターゲット」として指定します。

ターゲットナビゲータープロバイダーインターフェイスを実装するアプリでは、次の操作を実行できます。

  1. 利用可能なターゲットを照会 - アプリがナビゲーション用に提供している画面やセクションを検出します。
  2. 現在のターゲットを照会 - ユーザーが表示している画面やセクションを特定します。
  3. ターゲットに移動 - アプリの特定の画面やセクションに移動します。

ターゲットナビゲータープロバイダーAPIには、主な構成要素が3つあります。

  • handleGetCurrentTarget - アクティブなアプリターゲットを返すコールバックです。
  • handleGetAvailableTargets - サポートされているナビゲーションターゲットを返すコールバックです。
  • handleNavigateTargetRequest - システムが特定のターゲットナビゲーションをリクエストしたときに呼び出されるコールバックです。

プロバイダーは、次のメソッドを使用して状態の変化をプロアクティブに報告する必要があります。

  • updateCurrentTarget - 現在のターゲットが変更されたときにシステムに通知します。
  • updateAvailableTargets - 利用可能なターゲットのリストが変更されたときにシステムに通知します。

Vegaターゲットナビゲーターの前提条件

このAPIを使用する前に、アプリのマニフェストを更新して、VegaターゲットナビゲーターAPIを使用する意図を宣言してください。マニフェストエントリを変更するときは、com.amazondeveloper.media.sampleを、アプリの実際のパッケージIDに置き換えてください。アプリは、VegaターゲットナビゲーターAPIとやり取りするように正しく構成されている必要があります。

クリップボードにコピーしました。

schema-version = 1

[package]
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"
# 「com.amazon.category.kepler.media」カテゴリーはプライマリコンポーネントにのみ必要で、
# マニフェストの[[extras]]セクションの「component-id」値を使用して識別されます。
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]

# ターゲットナビゲーターインターフェイスを追加します
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.ITargetNavigator"

手順1： Vegaターゲットナビゲーターをインストールしてセットアップする

VegaターゲットナビゲーターAPIを使用するには、次の依存関係を追加してpackage.jsonファイルを更新します。

クリップボードにコピーしました。

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

手順2： 利用可能なターゲットを定義する

TargetInfoオブジェクトは、次のフィールドで各ターゲットを表します。

  • identifier（数値、必須）- アプリ内のターゲットの一意の数値ID。
  • name（文字列、任意）- 人間が読める形式のターゲットの名前。
  • standardId（StandardTargetIdentifier1、任意）- 既知の宛先にマッピングされる標準識別子で、システムがターゲットの目的を理解できるようにします。

使用可能な標準ターゲット識別子は次のとおりです。

StandardTargetIdentifier1 値 説明
HOME 0 アプリのホーム画面
LOGIN 1 ログイン画面
PROFILE 2 ユーザープロフィール
SETTINGS 3 アプリの設定
PRIVACY 4 プライバシー設定
HELP 5 ヘルプ画面
ABOUT 6 バージョン情報画面
TERMS 7 サービス利用規約
SEARCH 8 検索画面
RECOMMENDATIONS 9 おすすめ機能
TRENDING 10 話題のコンテンツ
DOWNLOADS 11 ダウンロード
HISTORY 12 視聴履歴

ターゲットを識別子をキーとするマップとして定義できます。

クリップボードにコピーしました。

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 },
};

ターゲットナビゲーターインターフェイスは、standardIdのないカスタムターゲットもサポートします。

クリップボードにコピーしました。

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

手順3： ターゲットナビゲーターハンドラーを実装する

3つのコールバックメソッドを実装するTargetNavigatorHandlerオブジェクトを作成します。

クリップボードにコピーしました。

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

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

  handleNavigateTargetRequest: (target: TargetInfo): Promise<string> => {
    // 提供されている場合はstandardIdによる照合を優先し、識別子にフォールバックします
    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');
  },
};

ハンドラーメソッドの詳細

メソッド 戻り値 説明
handleGetCurrentTarget() Promise<TargetInfo[]> 現在アクティブなターゲットを返します。配列がない場合は空の配列を返します。
handleGetAvailableTargets() Promise<TargetInfo[]> ナビゲーション可能なすべてのターゲットを返します。要素は256個以下にする必要があります。
handleNavigateTargetRequest(target) Promise<string> ターゲットに移動します。成功した場合はステータス文字列を返して解決し、失敗した場合はErrorを返して拒否します。

手順4： ハンドラーを登録する

useKeplerAppStateManager()からIComponentInstanceを使用してハンドラーを登録します。起動時にupdateメソッドを呼び出す前にこれを行わないでください。

クリップボードにコピーしました。

const componentInstance = useKeplerAppStateManager().getComponentInstance();

TargetNavigatorProvider.registerTargetNavigatorHandler(
  targetNavigatorHandler,
  componentInstance
);

手順5： ターゲットの状態変化を報告する

ハンドラーを登録したら、現在の状態をシステムに通知します。起動時にupdateCurrentTargetとupdateAvailableTargetsの両方を呼び出し、状態が変化した場合は再度呼び出します。

現在のターゲットの更新

ユーザーが別の画面に移動するたびに、アプリの初期化を呼び出します。

クリップボードにコピーしました。

TargetNavigatorProvider.updateCurrentTarget(availableTargets[2]);

遷移状態などで現在のターゲットがないことを示すには、undefinedを渡します。

クリップボードにコピーしました。

TargetNavigatorProvider.updateCurrentTarget(undefined);

利用可能なターゲットの更新

ユーザーのログイン時など、ナビゲート可能な対象が変更された場合はターゲットを更新します。

クリップボードにコピーしました。

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

Vegaターゲットナビゲーターのトラブルシューティング

問題 解決策
ハンドラーがリクエストを受け取らない マニフェストのinterface_nameが正確に"com.amazon.kepler.media.ITargetNavigator"であり、component-idが対話型コンポーネントと一致していることを確認します。
ターゲットが見つからないというエラー updateAvailableTargets()を使用して、利用可能なターゲットリストが最新の状態に保たれていることを確認します。
ハンドラの登録が遅すぎる リクエストが届く前に、マウント時にuseEffectに登録します。

APIリファレンス

クラス

インターフェイス

  • TargetInfo - ナビゲーションのターゲットを表します。
  • TargetNavigatorHandler - リクエストを処理するためにターゲットナビゲーターサーバーによって実装されるインターフェイス。

列挙型

Last updated: 2026年7月15日

フォローする

サポート対象デバイス

amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved. 無断複写·転載を禁じます。

利用規約

Amazon開発者ブログ

お問い合わせ