コンテンツランチャー統合ガイド

このドキュメントでは、コンテンツランチャーをアプリに統合する方法について説明します。メディアアプリは通常、次の3つの主要なAPIと統合する必要があります。

1. コンテンツランチャーAPI
2. VegaメディアコントロールAPI
3. アカウントログインAPI

システムは、コンテンツランチャーAPIとVegaメディアコントロールAPIを1つの対話型コンポーネントとして実装します。それがVegaメディアクエリを処理するメインコンポーネントです。アカウントログインAPIは、サービスコンポーネントとして機能します。

手順1： アプリのマニフェストファイルを更新する

アプリのmanifest.tomlファイルに、コンテンツランチャーのサポートを含めます。この例では、パッケージIDをcom.amazondeveloper.keplervideoappと想定しています。このパッケージIDをアプリのパッケージIDに置き換えてください。

アプリは、VegaメディアコンテンツランチャーAPIとやり取りするように構成する必要があります。

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

手順2： アプリで必要なパッケージの依存関係を追加する

package.jsonファイルに、依存関係として@amazon-devices/kepler-media-content-launcherパッケージを追加します。

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

手順3： コンテンツランチャーAPIを実装する

1. コンテンツランチャーハンドラーを定義します。

   新しいContentLauncherServerComponentをインスタンス化します。コールバック関数をカプセル化するハンドラーオブジェクトを作成します。

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

   import {
   ILauncherResponse,
   IContentLauncherHandler,
   ContentLauncherStatusType,
   ContentLauncherServerComponent,
   ILaunchContentOptionalFields,
   } from '@amazon-devices/kepler-media-content-launcher';
   
   ...
   // ContentLauncherServerComponentのインスタンスを作成します。
   let factory = new ContentLauncherServerComponent();
   
   // コンテンツの起動がリクエストされたときに呼び出されるハンドラーを作成します。
   const contentLauncherHandler: IContentLauncherHandler = {
      async handleLaunchContent(
         _optionalFields: ILaunchContentOptionalFields,
      ): Promise<ILauncherResponse> {
         console.log('Content_Launcher_Sample: handleLaunchContent invoked');
   
         // ここでデータを取得するために繰り返し処理を行い、
         // 起動リクエストを処理するビジネスロジック
   
         let launcherResponse = factory
               .makeLauncherResponseBuilder()
               .contentLauncherStatus(ContentLauncherStatusType.SUCCESS)
               .build();
         return Promise.resolve(launcherResponse);
      },
   };
   

   ハンドラーはリクエストを処理し、ILauncherResponseに解決されるPromiseを返す必要があります。これは、ContentLauncherServerComponentのインスタンスを使用して作成します。アプリが正常にリクエストを処理した場合は、LauncherResponseのcontentLauncherStatusのステータスをContentLauncherStatusType.SUCCESSに設定します。認可の問題が原因でアプリがリクエストを処理できなかった場合は、ステータスをContentLauncherStatusType.AUTH_FAILEDに設定します。それ以外の場合は、ステータスをContentLauncherStatusType.URL_NOT_AVAILABLEに設定します。

2. 対話型アプリにVegaメディアコンテンツランチャーを実装します。

   対話型アプリにVegaメディアコンテンツランチャーを実装するには、まずIContentLauncherServerAsyncのシングルトンインスタンスを取得します。ContentLauncherServerComponentインスタンスのgetOrMakeServerメソッドを使用して、IContentLauncherServerAsyncを実装します。次に、IContentLauncherHandlerインターフェイスを実装するハンドラーオブジェクトを作成して、コンテンツ起動リクエストを処理します。IContentLauncherServerAsyncインスタンスのsetHandlerForComponentを呼び出します。これにより、ハンドラーが正しいコンポーネントに関連付けられます。このとき、ハンドラーと適切なIComponentInstanceを渡します。対話型アプリでは、useComponentInstanceメソッドを使用してIComponentInstanceを取得できます。React Nativeアプリの場合は、useEffectフック内でハンドラーを設定します。コンポーネントがマウントされ、IComponentInstanceが利用可能になったらすぐに、コンテンツランチャーを初期化する必要があります。これにより、コンテンツランチャーの機能がコンポーネントのライフサイクルと緊密に統合されます。また、アプリが初期化された時点から、Vegaコンテンツランチャーのコマンドを効率的に処理することが可能になります。このセットアップでは、各コンポーネントでIComponentInstanceが使用され、コールバックルーティングの混乱を防ぐことができます。これは複数のコンポーネントを使用するアプリにとって重要です。

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

   import { useComponentInstance, IComponentInstance } from '@amazon-devices/react-native-kepler';
   
   export const App = () => {
   
   const componentInstance: IComponentInstance = useComponentInstance();
   
   useEffect(() => {
      const factory = new ContentLauncherServerComponent();
   
      const contentLauncherHandler: IContentLauncherHandler = {
   
         async handleLaunchContent(
         _optionalFields: ILaunchContentOptionalFields,
         ): Promise<ILauncherResponse> {
         console.log('Content_Launcher_Sample: handleLaunchContent invoked.');
   
         // 繰り返し処理して..
         //..ここでデータを取得します
   
         const launcherResponse = factory
            .makeLauncherResponseBuilder()
            .contentLauncherStatus(ContentLauncherStatusType.SUCCESS)
            .build();
   
         return Promise.resolve(launcherResponse);
         },
      };
   
      const contentLauncherServer = factory.getOrMakeServer();
      contentLauncherServer.setHandlerForComponent(contentLauncherHandler,componentInstance);
   
      return () => {};
   }, []);
   
   // ここでプロバイダーアプリのユーザーインターフェイスを作成します。
   };
   

実装の詳細

IContentLauncherHandlerハンドラーは、再生または検索結果に表示するコンテンツを定義するパラメーターを1つ受け取ります。

• ILaunchContentOptionalFieldsインターフェイスを実装しているオブジェクトへのポインターを介して渡されるオプションフィールド。

コンテンツランチャーリクエストの例

以下の例では、コンテンツランチャーの主なユースケースにおけるcontentSearchパラメーターの値について説明します。これらの例は、サポートされているすべてのユースケースの一覧です。どのユースケースでも、コンテンツランチャーが呼び出され、アプリが起動します。

以下はstreamz_usのサンプルカタログで、エントリの例として「Seabound」という映画と「The SeaShow: The Real Story」というTV番組が含まれています。

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

リモコンによるコンテンツの起動

Vega TVのホーム画面から、リモコンを使用して映画「Seabound」を起動します。

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

アプリでは、tv.streamz/movie/46720000をLaunchIdとして使用して映画を特定し、直接再生する必要があります。

音声によるクイック再生

音声を使用して映画「Seabound」を再生します。「アレクサ、『Seabound』を再生して」という発話を使用します。

ここではautoPlayはtrueになります。以下の例は、contentSearch: IContentSearchの値を示しています。アプリが起動し、ID 1700000725を使用してコンテンツが直接再生されます。

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

音声による特定のエピソードの再生

以下のサンプルカタログは、TV番組「SeaShow: The Real Story」と、そのシーズンおよびエピソードを表しています。Alexaに「アレクサ、『The SeaShow: The Real Story』のシーズン2、エピソード5を再生して」という発話を使用すると、アプリが呼び出され、指定されたエピソードが再生されます。

ここではautoPlayはtrueになります。contentSearchには、エピソードIDではなく番組IDが含まれます。アプリでは、ID 1700000123、ContentSearchParamType::SEASON、ContentSearchParamType::EPISODEの各値を使用してエピソードを正確に特定する必要があります。

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

---

Last updated: 2026年3月23日