Amazon Developer

Console

as

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

Console

as

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

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

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

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

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

正しい依存関係を追加してマニフェストを更新する方法の詳細については、APIのREADMEファイルの@amazon-devices/kepler-media-content-launcherを参照してください。

Vegaメディアコンテンツランチャーの一般的なユースケース

VegaメディアコンテンツランチャーAPIの使用を開始するには、以下の手順を実行します。

  • 新しいContentLauncherServerComponentをインスタンス化します。コールバック関数をカプセル化するハンドラーオブジェクトを作成します。この関数は、ILauncherResponseに解決されるPromiseを返す必要があります。これは、ContentLauncherServerComponentインスタンスを使用して作成します。検索パラメーターを取得する方法については、このガイドの後半で説明します。コールバック関数では以下を行う必要があります。
    • コンテンツの起動リクエストを処理します。
    • LauncherResponseに適切なステータスを設定します。
      • ContentLauncherStatusType.SUCCESS（リクエストが正常に処理された場合）
      • ContentLauncherStatusType.AUTH_FAILED（認可の問題で処理できなかった場合）
      • ContentLauncherStatusType.URL_NOT_AVAILABLE（その他すべての場合）

コンテンツランチャーAPIの実装

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

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

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

     import {
   ILauncherResponse,
   IContentLauncherHandler,
   ContentLauncherStatusType,
   ContentLauncherServerComponent,
   IContentSearch,
   ILaunchContentOptionalFields,
 } from '@amazon-devices/kepler-media-content-launcher';

 ...
 // ContentLauncherServerComponentのインスタンスを作成します。
 const factory = new ContentLauncherServerComponent();

 // コンテンツの起動がリクエストされたときに呼び出されるハンドラーを作成します。
 const contentLauncherHandler: IContentLauncherHandler = {
     async handleLaunchContent(
       contentSearch: IContentSearch,
       autoPlay: boolean,
       optionalFields: ILaunchContentOptionalFields,
     ): Promise<ILauncherResponse> {
         console.log('Content_Launcher_Sample: handleLaunchContent invoked');

         // ここでデータを取得するために繰り返し処理を行い、
         // 起動リクエストを処理するビジネスロジックを追加します。

         const 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メディアコンテンツランチャーを実装します。

    1. IContentLauncherServerAsyncのシングルトンインスタンスを取得します。ContentLauncherServerComponentインスタンスのgetOrMakeServerメソッドを使用して、IContentLauncherServerAsyncを実装します。
    2. IContentLauncherHandlerインターフェイスを実装するハンドラーオブジェクトを作成して、コンテンツ起動リクエストを処理します。
    3. IContentLauncherServerAsyncインスタンスのsetHandlerForComponentを呼び出します。これにより、ハンドラーが正しいコンポーネントに関連付けられます。
    4. ハンドラーと適切な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(
                  contentSearch: IContentSearch,
                  autoPlay: boolean,
                  _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 () => {};
      }, []);

      // ここでプロバイダーアプリのユーザーインターフェイスを作成します。
  };

実装の詳細

handleLaunchContentコールバック関数には、次の3つのパラメーターがあります。

  1. IContentSearchインターフェイスを実装しているオブジェクト。
  2. autoPlayと呼ばれるブール値。
  3. ILaunchContentOptionalFieldsインターフェイスを実装しているオブジェクトとして渡される追加フィールド。

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

autoPlayに基づくアクションの決定

autoPlayパラメーターは、ハンドラーの動作を以下のように制御します。

  • autoPlayがtrueに設定されている場合： クイック再生のリクエストを示します。ユーザーに追加の操作を求めることなく、指定されたコンテンツの再生をすぐに開始する必要があります。
  • autoPlayがfalseに設定されている場合： ハンドラーは再生を開始することなく、検索結果をユーザーに表示する必要があります。これにより、ユーザーは使用可能なオプションを確認して選択できます。

特にautoPlayのようなパラメーターを活用することで、IContentLauncherHandlerでコンテンツの検出と再生を効率的に管理できます。

検索の値の取得

IContentSearchパラメーターには、検索対象のコンテンツ情報が格納されます。以下は、IContentSearchに格納される値のスキーマです。

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

1     "parameterList": [{
1.1     "type": "<エンティティタイプ>",
1.2     "value": "<エンティティの値>",
1.3     "externalIdList": [{
1.3.1          "name": "<外部ID名>",
1.3.2          "value": "<外部IDの値>"
        }]
      }]
  • parameterListには1つ以上のエントリがあります。contentSearch.getParameterList().lengthはパラメーターの数を返します。完全なリストを取得するにはgetParameterList()を使用します（スキーマの1行目）。
  • パラメーターにリストされているエンティティのタイプを表します。たとえば、映画やTV番組の場合、"type"は「ContentSearchParamType::VIDEO」になります。サポートされている値の一覧については、「ContentSearchParamType」の列挙型を参照してください。タイプを取得するにはgetParamType()を呼び出します（スキーマの1.1行目）。
  • タイプで指定されたエンティティの値を表します。このフィールドを取得するにはgetValue()を呼び出します（スキーマの1.2行目）。各パラメーターには0個以上のexternalIdsが含まれます。リストのサイズを取得するにはgetExternalIdList().lengthを使用します。getExternalIdList()を使用すると、完全なリストが返されます（スキーマの1.3行目）。
  • <外部ID名> はgetName()で取得します。2つの名前を認識できます （スキーマの1.3.1行目）。amzn_id - リクエストされたコンテンツのカタログID。launch_url - Matterキャストなどの外部エクスペリエンスから提供されるディープリンク文字列。直接再生を開始するために使用できます。
  • <外部IDの値> はexternalIdの値を表します。値を取得するにはgetValue()を使用します。amzn_idの場合、この値はカタログ統合で使用されている <ID> または <launchId> と同じ値になります。launch_urlの場合、この値はリクエスト元のエクスペリエンスから提供された完全なディープリンクになります。

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

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

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

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

...
<Movie>
  <ID>1700000725</ID>
  <Title locale="en-US">Seabound</Title>
  <Offers>
    <SubscriptionOffer>
      <LaunchDetails>
        <Quality>UHD</Quality>
        <Subtitle>en-US</Subtitle>
        <LaunchId>tv.streamz/movie/46720001</LaunchId>
      </LaunchDetails>
    </SubscriptionOffer>
    <FreeOffer>
      <Regions>
        <Territories>US</Territories>
      </Regions>
      <LaunchDetails>
        <Quality>SD</Quality>
        <Subtitle>en-US</Subtitle>
        <LaunchId>tv.streamz/movie/467200002</LaunchId>
      </LaunchDetails>
    </FreeOffer>
  </Offers>
</Movie>

<TvShow>
  <ID>1700000123</ID>
  <Title locale="en-US">The SeaShow: The Real Story</Title>
  <Offers>
    <FreeOffer>
      <Regions>
        <Territories>US</Territories>
      </Regions>
      <LaunchDetails>
        <Quality>HD</Quality>
        <Subtitle>en-US</Subtitle>
        <LaunchId>459800033</LaunchId>
      </LaunchDetails>
    </FreeOffer>
  </Offers>
</TvShow>

<TvSeason>
  <ID>1700000234</ID>
  <Title locale="en-US">Season 1</Title>
    <Offers>
     <FreeOffer>
       <Regions>
         <Territories>US</Territories>
       </Regions>
       <LaunchDetails>
         <Quality>HD</Quality>
         <Subtitle>en-US</Subtitle>
         <LaunchId>453200012</LaunchId>
        </LaunchDetails>
     </FreeOffer>
   </Offers>
   <ShowID>1700000123</ShowID>
   <SeasonInShow>2</SeasonInShow>
</TvSeason>

<TvEpisode>
  <ID>1700000825</ID>
  <Title locale="en-US">The Seashow.Story Starts</Title>
  <Offers>
    <FreeOffer>
      <Regions>
        <Territories>US</Territories>
      </Regions>
      <LaunchDetails>
        <Quality>HD</Quality>
        <Subtitle>en-US</Subtitle>
        <LaunchId>453100008</LaunchId>
      </LaunchDetails>
    </FreeOffer>
  </Offers>
  <ShowID>1700000123</ShowID>
  <SeasonID>1700000234</SeasonID>
  <EpisodeInSeason>5</EpisodeInSeason>
</TvEpisode>
...

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

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

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

"parameterList": [
    {                                               // パラメーター0。
        "type": 13,                                 // ContentSearchParamType::VIDEO
        "value": "",                                // コンテンツのタイトルは含まれません。
        "externalIdList": [
            {
                "name": "catalogContentId",         // 廃止される予定です。 これは無視してください。
                "value": "tv.catalog/movie/46720000" // カタログからのIDまたはLaunchId。
            },
            {
                "name": "amzn_id",
                "value": "tv.catalog/movie/46720000" // カタログからのIDまたはLaunchId。
            }
        ]
    }
]

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

音声によるクイック再生

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

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

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

[
    {                             // パラメーター0。
        "type": 13,               // ContentSearchParamType::VIDEO
        "value": "Seabound",      // 検索文字列。
        "externalIdList": [{
            "name": "streamz_us"  // カタログID。 廃止される予定です。 これは無視してください。
            "value": "1700000725" // カタログからのID。
        },
        { 
            "name": "amzn_id"  
            "value": "1700000725" // カタログからのID。
        }
      ]
    }
]

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

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

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

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

"parameterList": [
    {
        "type": 13,
        "value": "",
        "externalIdList": [
            {
                "name": "catalogContentId",
                "value": "tv.catalog/movie/46720000"
            },
            {
                "name": "amzn_id",
                "value": "tv.catalog/movie/46720000"
            }
        ]
    }
]

例： Alexaを使用してエピソードを起動する

以下の例では、 「Streamzで『The SeaShow： The Real Story』のシーズン2、エピソード5を見せて」というAlexaへの発話を使用してエピソードを起動します。

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

// 繰り返し処理を行いデータを取得します。
const searchParameters = contentSearch.getParameterList();
if (searchParameters.length > 0) {
    for (const searchParameter of searchParameters) {
        const paramType = searchParameter.getParamType();
        const searchString = searchParameter.getValue();

        const additionalInfoList = searchParameter.getExternalIdList();
        for (const additionalInfo of additionalInfoList) {
            const searchName = additionalInfo.getName();
            const entityID = additionalInfo.getValue();

            switch (searchName) {
                case 'amzn_id':
                    // このエンティティIDを使用してカタログ内で正確なコンテンツを検索します。
                    break;
                case 'launch_url':
                    // このディープリンクURLを使用して再生を直接開始します。
                    break;
                // アプリでサポートされるその他の外部ID名がある場合は、case文をここに追加します。
                default:
                    // 外部ID名を認識できない場合はフォールスルーします。
                    break;
            }
        }
    }

    if (autoPlay === true) {
        console.log(`Content_Launcher_Sample: Quickplay`);
        // 取得したデータを使用して、ここで再生ロジックを処理します。
    } else {
        console.log(`Content_Launcher_Sample: In-App search`);
        // 取得したデータを使用して、ここで検索ロジックを処理します。
    }
} else {
    console.log('Content_Launcher_Sample： 検索文字列を取得中にエラーが発生しました');
}

Last updated: 2026年6月18日

フォローする

サポート対象デバイス

amazon_developer_logo

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

利用規約

Amazon開発者ブログ

お問い合わせ