手順1： アプリにFire TVランチャーを統合する

アプリをAmazon Fire TVランチャーに対応させるために変更を加えると、メディアコンテンツとユーザーの定期購入ステータスがAmazon Fire TVユーザーインターフェイス内のほかのコンテンツと統合されます。このプロセスは、Amazon Fire TVと開発者双方のコンテンツを結び付ける「ディープリンク」とも呼ばれています。アプリにランチャーを統合すると、カタログ統合されたAmazonデバイスから、ユーザーの検索に応じてコンテンツを見つけて起動できるようになります。このページでは、カタログをFire TVランチャーに統合するために必要なアプリの変更点について説明します。

• ランチャー統合の概要
• 手順A： アプリの機能情報を含むインテントをアプリからブロードキャストする
  • インテントの種類：再生インテントとサインインインテント
  • インテントの作成と送信
  • インテントエクストラ
  • 例
• 手順B： ランチャーからの機能リクエストを受信する
• 手順C： ランチャーからの再生インテントおよびサインインインテントを処理する
• 手順D： カタログと利用可能なコンテンツ間の同期問題に対処するエラー処理コードを追加する
• 手順E： Androidマニフェストを構成する
  • 再生およびサインイン用のインテントフィルターを追加する
  • ランチャーのリクエストに対応するレシーバーを追加する
  • パーミッションを追加する
• 手順F： ランチャー統合をテストする
• ランチャー統合のユーザーエクスペリエンス（UX）ガイドライン
• ランチャー統合に関するよくある質問（FAQ）
• 次のステップ

ランチャー統合の概要

ユーザーがFire TVでアプリを起動すると、そのアプリからFire TVランチャーにAndroidブロードキャストが送信されます。このブロードキャストには、ディープリンクに使用されるAPKのクラス名（com.contentcompany.playerなど）が含まれています。ユーザーがアプリでコンテンツを起動すると、Fire TVではブロードキャストで指定されたクラスが起動し、カタログで構成されたコンテンツ視聴タイプのLaunchIdが渡されます。

ブロードキャストでは、クラス名のほかに、ランチャーで呼び出されるクラスに関するメタデータも送信します。以下のインテントをブロードキャストに含めることができます。

• サインインインテント
• 再生インテント

Fire TVランチャーとの統合には、ブロードキャストインテントの送信に加えて、アプリで以下の操作を行う必要があります。

• ランチャーから機能リクエストを受信し、アプリの機能を含むブロードキャストインテントと同じ情報で応答する。
• ランチャーからの再生リクエストまたはサインインリクエストを処理する。
• カタログと利用可能なコンテンツ間の同期問題を確認し、エラーを処理する。
• 必要なフィルター、レシーバー、パーミッションをAndroidマニフェストで指定する。

各タスクの詳細については、この後のセクションで説明します。

また、アプリは以下の処理にも対応する必要があります。

• 再生およびサインインに関するアクティビティと動作
• 提供しているサービスにおけるユーザーの定期購入ステータスの管理

手順A： アプリの機能情報を含むインテントをアプリからブロードキャストする

コンテンツを再生するには、アプリからFire TVランチャーにユーザーの情報を送信する必要があります。これにより、コンテンツを後で再生したり、サービスへのサインインをリクエストしたりすることが可能になります。アプリでは、この情報をAndroidブロードキャストインテントとして以下のタイミングで送信する必要があります。

• アプリの起動時
• ランチャーからリクエストされたとき（手順B： ランチャーからの機能リクエストを受信するを参照）
• ユーザーの定期購入ステータスが変更されたとき（ユーザーがサービスにサインインした場合や、サービスからサインアウトした場合など）
• ユーザーが定期購入型アイテムを購入、更新、またはアップグレードしたとき

インテントの種類：再生インテントとサインインインテント

Fire TVランチャーの統合とディープリンク用に、2種類のAndroidインテントを作成します。これらをアプリからブロードキャストする必要があります。

この2種類のインテントを使用して、アプリの機能をAmazon Fire TVに伝達します。

インテントの作成と送信

アプリの機能をブロードキャストするには、標準のAndroidインテントを構築し、sendBroadcast()メソッド（英語のみ）を使用してアプリのコンテキストに送信します。インテントの構築時には、以下の手順を実行する必要があります。

• インテントのパッケージ名をcom.amazon.tv.launcherにする。
• インテントアクションをcom.amazon.device.CAPABILITIESに設定する。
• その他のすべてのインテント情報をインテントエクストラとして指定する。

以下の例では、ブーリアン型の変数であるuserIsSignedInに基づいて、異なるインテントエクストラをブロードキャストするBroadcastCapabilities()メソッドを示します。この例の値はすべてサンプルデータであり、実際の値に置き換える必要があります。

public void BroadcastCapabilities(Context context)
{
    final Intent intent = new Intent();
    intent.setPackage("com.amazon.tv.launcher");
    intent.setAction("com.amazon.device.CAPABILITIES");
    if (userIsSignedIn) {
        // 再生インテントエクストラ
        intent.putExtra("amazon.intent.extra.PLAY_INTENT_ACTION","android.intent.action.VIEW");
        intent.putExtra("amazon.intent.extra.PLAY_INTENT_PACKAGE","com.contentcompany.player");
        intent.putExtra("amazon.intent.extra.PLAY_INTENT_CLASS","com.contentcompany.player.PlayActivity");
        intent.putExtra("amazon.intent.extra.PLAY_INTENT_FLAGS", Intent.FLAG_ACTIVITY_NEW_TASK | Intent.MORE_FLAGS);
    } else {
        // サインインインテントエクストラ
        intent.putExtra("amazon.intent.extra.SIGNIN_INTENT_ACTION","android.intent.action.VIEW");
        intent.putExtra("amazon.intent.extra.SIGNIN_INTENT_PACKAGE","com.contentcompany.player");
        intent.putExtra("amazon.intent.extra.SIGNIN_INTENT_CLASS","com.contentcompany.player.SignInActivity");
        intent.putExtra("amazon.intent.extra.SIGNIN_INTENT_FLAGS", Intent.FLAG_ACTIVITY_NEW_TASK | Intent.MORE_FLAGS);
    }
    
    intent.putExtra("amazon.intent.extra.DATA_EXTRA_NAME", "contentId");
    intent.putExtra("amazon.intent.extra.PARTNER_ID","contentcompany");

    // ブロードキャストをランチャーに送信する
    context.sendBroadcast(intent);
}

インテントエクストラ

アプリの機能をエクストラフィールドのキーと値に指定するには、Intent.putExtra()メソッドを使用します。インテントエクストラでは、常にamazon.intent.extraというプレフィックスパッケージが使用されます。

以下の表は、必須のインテントエクストラと、再生インテントとサインインインテントに固有のエクストラについて説明したものです。すべてのインテントエクストラの値は、先頭にamazon.intent.extraが付きます。

以下の1つのエクストラは常に必要です。

• Amazonから提供されたパートナーID（PARTNER_ID）。このIDは、カタログ統合に使用するIDと同じものです。

残りのインテントエクストラは、ユーザーにコンテンツの再生権限があるかどうか（サインインしているかどうか）、または続行前にサインインする必要があるかどうかによって異なります。

• ユーザーがサインイン済みの場合は、プレフィックスがPLAY_のエクストラが必須になります。
• ユーザーがサインインしていない場合は、プレフィックスがSIGNIN_のエクストラが必須になります。

例

ユーザーがサインインしたときやアプリをアクティベートしたときは、以下のエクストラを指定したインテントを送信します。

• PARTNER_ID
• PLAY_INTENT_ACTION
• PLAY_INTENT_PACKAGE
• PLAY_INTENT_CLASS
• PLAY_INTENT_FLAGS

また、ランチャーからアプリの機能をリクエストされたときにユーザーがサインインしていない場合は、以下のエクストラを指定したインテントを送信します。

• PARTNER_ID
• SIGNIN_INTENT_ACTION
• SIGNIN_INTENT_PACKAGE
• SIGNIN_INTENT_CLASS
• SIGNIN_INTENT_FLAGS

上記に挙げたインテントエクストラの両セットは、同時に指定しないでください。PLAY_で始まるキーがあると、ユーザーにコンテンツの再生権限があるものとみなされてしまいます。

手順B： ランチャーからの機能リクエストを受信する

Fire TVランチャーから、アプリの機能とユーザーの定期購入ステータスに関するリクエストを受け取ることがあります。ランチャーがこの情報をリクエストするときは、アクションがcom.amazon.device.REQUEST_CAPABILITIESに設定されたAndroidブロードキャストインテントが使用されます。アプリ側は、手順A： アプリの機能情報を含むインテントをアプリからブロードキャストするで作成したものと同じインテントで応答する必要があります。

以下の例では、ランチャーのブロードキャストインテントを処理する簡単なクラスを示します。ランチャーに送信する機能情報は、手順A： アプリの機能情報を含むインテントをアプリからブロードキャストするで送信する情報と同じであるため、両方のタスクの処理に同じメソッド（ここではBroadcastCapabilities()）を使用できます。

public class CapabilityRequestReceiver extends BroadcastReceiver
{
   @Override public void onReceive(Context context, Intent intent)
   {
      BroadcastCapabilities(); //アプリの情報をランチャーにブロードキャストするために使用するメソッド
   }
}

手順C： ランチャーからの再生インテントおよびサインインインテントを処理する

ユーザーがFire TVユーザーインターフェイスでコンテンツの詳細を確認しようとすると、サービスにおけるユーザーのステータスに応じて、Fire TVに異なるオプションが表示されます。

• ユーザーがサービスにサインイン済みの場合（機能のブロードキャストでPLAY_インテントエクストラを指定した場合）、アプリの表示名が記載されたボタンが表示されます（例：「MyCompany Player」）。ユーザーがこのボタンをクリックすると、ランチャーからアプリに再生インテントが送信されます。
• ユーザーがサインインしていない場合（SIGNIN_インテントエクストラを指定した場合）、「Launch」に続いてアプリの表示名が記載されたボタンが表示されます（例：「Launch MyCompany Player」）。ユーザーがこのボタンをクリックすると、ランチャーからアプリにサインインインテントが送信されます。

どちらの場合も、ランチャーは機能のブロードキャストで指定された情報を使用して、アプリに送信する再生インテントとサインインインテントの両方を構築します。

再生インテントまたはサインインインテントを処理するには、これらのインテントを受信して処理し、リクエストされたコンテンツを再生するアクティビティをアプリに実装します。

以下のコードは再生アクティビティの概略を示しています。

public class PlayActivity extends Activity {
   @Override
   public void onCreate(Bundle bundle) {
      super.onCreate(bundle);
      Uri data = getIntent().getData();
      //'data'によって指定されたコンテンツを再生する
      // または
      String data = getIntent.getStringExtra("titleExtra");
      //DATA_EXTRA_NAMEで示すエクストラによって指定されたコンテンツを再生する
   }
}

再生インテントとサインインインテントにはリクエストされたコンテンツのIDが含まれているため、アプリでは、そのコンテンツを即座に再生したり（再生インテント）、ユーザーのサインイン後に再生したり（サインインインテント）できます。コンテンツのIDとID形式は、カタログ統合の一環としてメディアカタログで指定します。

コンテンツIDがURI形式でない場合（例：123456）、ランチャーはそのIDを、開発者が機能のブロードキャスト時にDATA_EXTRA_NAMEで指定したエクストラとして送信します。そのコンテンツIDには、Intent.getStringExtra()メソッドを使用してアクセスしてください。

ユーザーが [戻る] ボタンを連続して押したときは（メディア再生の画面からは通常3回）、最終的に、ユーザーがアプリを開いた場所に戻れるようにする必要があります。今回の場合、ランチャーの検索結果がその場所にあたります。

手順D： カタログと利用可能なコンテンツ間の同期問題に対処するエラー処理コードを追加する

Fire TVに統合されたアプリの多くに共通する問題として、カタログと利用可能なコンテンツが同期されなくなることがあります。ユーザーが検索や閲覧を通じてコンテンツアイテムを選択したものの、実際には再生できない場合、ナビゲーションが困難な黒い画面が表示されてしまいます。このような状況はユーザーに大きなストレスを与え、Fire TVでのアプリ使用に悪影響を及ぼしかねません。

同期の問題が起こる理由には、以下が考えられます。

• 新しいカタログをアップロードしたばかりで、カタログが正常に統合されてからコンテンツが再生可能になるまでに数時間の差がある。
• コンテンツの一部を置き換えたが、この変更を反映したカタログのアップデート版がまだアップロードされていない、または統合されていない。

利用できないコンテンツが選択された際に黒い画面が表示されないように、Amazonではエラー処理コードをアプリに実装することを推奨しています。ユーザーが利用できないコンテンツを選択しようとした際に、わかりやすいエラーメッセージを表示して、適切な場所にリダイレクトかけるようなコードにしてください。問題が発生しても上手に対応すれば、よりポジティブなユーザーエクスペリエンスに変えることができるはずです。

手順E： Androidマニフェストを構成する

ランチャーからのブロードキャストインテントを処理できるように、Androidマニフェストを構成します。具体的には、以下の3つの要素を追加します。

• 再生インテントとサインインインテントを処理するインテントフィルター
• ランチャーからの機能リクエストのインテントに対応するレシーバー
• インテントを適切なパーミッションで送信するためパーミッション

再生およびサインイン用のインテントフィルターを追加する

ランチャーからインテントを受信するために、再生アクティビティとサインインアクティビティ用のインテントフィルターを追加します。以下の例では、PlayActivityという名前の再生アクティビティを使用しています。

<activity
    android:name=".PlayActivity"
    android:label="Playback Activity">
    ...
    <intent-filter>
        <action android:name="com.contentcompany.player.PlayActivity">
        <category android:name="android.intent.category.DEFAULT">
    </intent-filter>
</activity>

ランチャーのリクエストに対応するレシーバーを追加する

マニフェストにreceiver要素を追加してBroadcastReceiverクラスの名前を指定し、com.amazon.device.REQUEST_CAPABILITIESアクションに対するintent-filterを含めます。以下の例では、レシーバークラスをCapabilityRequestReceiverにしています。

<receiver android:name="CapabilityRequestReceiver" >
    <intent-filter>
    <action android:name="com.amazon.device.REQUEST_CAPABILITIES" />
    </intent-filter>
</receiver>

パーミッションを追加する

ランチャーがインテントを確実に受信できるように、マニフェストにuses-permission要素を追加します。

<uses-permission android:name="com.amazon.device.permission.COMRADE_CAPABILITIES" />

手順F： ランチャー統合をテストする

アプリにFire TVランチャーを統合したら、Amazonアプリストアにアプリを申請する前に、ランチャー統合を検証する必要があります。

アプリの申請前に実行するテストケースのフローについては、手順2： カタログのディープリンクを検証するを参照してください。

ランチャー統合のユーザーエクスペリエンス（UX）ガイドライン

ランチャーを統合する際には、以下のユーザーエクスペリエンスを念頭に置いてください。

• ユーザーがFire TVのユニバーサル検索・閲覧の結果からアプリのコンテンツを選択したら、すぐに再生が開始されるようにします。再生開始前に、ユーザーをアプリのホーム画面やコンテンツの詳細画面に誘導することは避けてください。
• ただし、ユーザーがコールドスタートから再生ディープリンクを開き、そのユーザーがアプリに複数のプロフィールを登録している場合は例外です。その場合、再生を開始する前にプロフィール選択画面を表示してください。これにより、ユーザーが意図したものとは別のプロフィールでコンテンツを視聴するのを防ぐことができます。ディープリンクのシナリオについて詳しくは、テストケース：ディープリンクを参照してください。
• ランチャー統合の一環として、アプリが開かれるたびに、または定期購入ステータスが変更されるたびに、ユーザーの定期購入ステータスを発行します。そうすることで、コンテンツがアプリ外で表示された場合でも、定期購入ユーザーに [今すぐ観る] オプションが表示されるようになります。 
• 現在のカタログ内容が実際に利用可能なコンテンツと一致しなくなった場合に備えて、エラー処理コードを実装します。ユーザーが再生できないコンテンツを選択した場合に、不満を感じないように対処してください。このシナリオに対応するエラー処理コードを実装しないと、ユーザーには黒い画面が表示され、Fire TVやアプリ、カタログなどの画面に戻るのが困難になります。これはユーザーの混乱を招き、ユーザーエクスペリエンスの低下につながります。

ランチャー統合に関するよくある質問（FAQ）

Q： ユーザーが閲覧・検索を通じてエピソードやシリーズを選択した場合、どのように再生を始めるべきですか？

A： 優れたユーザーエクスペリエンスを提供するために、検索・閲覧の結果からエピソードやシリーズに直接ディープリンクして再生を開始してください。アプリのホーム画面やそのほかの場所にユーザーを誘導することは避けてください。

Q： ユーザーがエピソードやシリーズを選択した際に、どのくらい早く再生を開始すべきですか？

A： 再生開始までにかかる時間は、バッファー処理やその他の要因によってアプリごとに異なります。ただし、コンテンツが選択された後は、ほかの手順を挟まずに再生がすぐに開始される必要があります。再生開始前にユーザーをアプリのホーム画面やその他の場所にリダイレクトしないでください。

Q： 再生が終了したら、どの画面を表示すべきですか？

A： 統合されたカタログからではなく、アプリ経由でコンテンツにアクセスした場合は、ユーザーが期待するであろう画面を表示するようにしてください。アプリによっては、次のエピソードの再生が自動的に開始する場合や、おすすめコンテンツの画面が表示される場合があります。Fire TV経由でコンテンツにアクセスする場合でも、アプリ内でコンテンツにアクセスする場合でも、ユーザーエクスペリエンスの一貫性を保つようにしてください。

次のステップ

ランチャーとの統合が完了したら、 手順2： カタログのディープリンクを検証するに進んでください。

Last updated: 2024年9月27日