手順1: アプリとFire TVのホーム画面ランチャーを統合する


手順1: アプリとFire TVのホーム画面ランチャーを統合する

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

プロセスの概要

アプリとFire TVのホーム画面ランチャーを統合するには、以下の手順を実行します。

  1. ユーザーの定期購入ステータスと、アプリ機能に関するその他の情報を含むAndroidインテントをブロードキャストします。
  2. Fire TVランチャーからの機能リクエストを受信し、手順A: アプリの機能情報を含むインテントをアプリからブロードキャストするで作成したインテントで応答します。
  3. Fire TVランチャーから再生リクエストまたはサインインリクエストを受信します。
  4. カタログと利用可能なコンテンツ間の同期問題に対処するエラー処理コードを追加します。
  5. すべての変更を処理するために、Androidマニフェストを構成します。
  6. ランチャー統合を検証します。
  7. アップデートしたアプリをユーザーに向けて再公開します。

また、以下に関して引き続き対応を続ける必要もあります。

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

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

コンテンツを再生するには、Fire TVのホーム画面ランチャーにアプリユーザーの情報を送る必要があります。そうすることでコンテンツを後で再生したり、サービスへのサインインをリクエストしたりすることができるようになります。この情報は、以下の場合にAndroidブロードキャストインテントとしてアプリ経由で送信してください。

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

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)
{
    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.PARTNER_ID","contentcompany");
    intent.putExtra("amazon.intent.extra.DISPLAY_NAME","Our Video App");

    //インテントをFire TVランチャーに送信する
    context.sendBroadcast(intent);
}

インテントエクストラ

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

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

インテントエクストラ 使用機会 説明
PARTNER_ID 常時 Amazonから提供されるパートナーIDは、カタログ統合でCDFファイルのパートナーフィールドに使用するIDと同じです。このIDは、個人や組織ではなくアプリに固有のものになるので、Fire TVアプリが複数ある場合は、それぞれに異なるパートナーIDが割り当てられます。
DATA_EXTRA_NAME 条件付き データのコンテンツIDを含むエクストラの名前です(例:titleData)。この値は、コンテンツIDがURIで記述されていない場合にのみ指定してください。コンテンツIDがURI形式でない場合(例:123456)、DATA_EXTRA_NAMEを使用して、Fire TVランチャーでIDとして使用するインテントエクストラの名前を指定します。(詳細については、手順C: Fire TVランチャーからの再生インテントおよびサインインインテントを処理するを参照してください)。コンテンツIDにアクセスする際は、Intent.getStringExtra()メソッドを使用します。
PLAY_INTENT_ACTION ユーザーがサインイン済みの場合 再生インテント用で、Fire TVランチャーが送信するインテントアクションのことです(通常はandroid.intent.action.VIEW)。
PLAY_INTENT_PACKAGE ユーザーがサインイン済みの場合 再生インテント用で、アプリのパッケージを指します(例:com.contentcompany.player)。
PLAY_INTENT_CLASS ユーザーがサインイン済みの場合 再生インテント用で、アプリの完全なパッケージ名とクラス名です(例:com.contentcompany.player.PlayActivity)。
PLAY_INTENT_FLAGS ユーザーがサインイン済みの場合 再生インテント用で、アプリがインテントから受け取る必要のあるフラグ(整数)です。使用できるフラグ値については、AndroidリファレンスガイドのIntent(インテント)を参照してください。
SIGNIN_INTENT_ACTION ユーザーがサインアウトしている場合 サインインインテント用で、Fire TVランチャーが送信するインテントアクションのことです(通常はandroid.intent.action.VIEW)。
SIGNIN_INTENT_PACKAGE ユーザーがサインアウトしている場合 サインインインテント用で、アプリのパッケージを指します(例:com.contentcompany.player)。
SIGNIN_INTENT_CLASS ユーザーがサインアウトしている場合 サインインインテント用で、アプリのクラス名です(例:SignInActivity)。
SIGNIN_INTENT_FLAGS ユーザーがサインアウトしている場合 サインインインテント用で、アプリがインテントから受け取る必要のあるフラグ(整数)です。使用できるフラグ値については、AndroidリファレンスガイドのIntent(インテント)を参照してください。

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

  • Amazonから提供されるパートナーID(PARTNER_ID)。このIDは、カタログ統合に使用するIDと同じものです。
  • アプリの表示名(DISPLAY_NAME)。この表示名はFire TVランチャーで使用され、該当するタイトルの再生ボタンやサインインボタンに表示されます。

残りのインテントエクストラは、ユーザーにコンテンツの再生権限があるかどうか(サインインしているかどうか)、または処理を進めるにあたってサインインする必要があるかどうかによって異なります。

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

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

  • PARTNER_ID
  • DISPLAY_NAME
  • PLAY_INTENT_ACTION
  • PLAY_INTENT_PACKAGE
  • PLAY_INTENT_CLASS
  • PLAY_INTENT_FLAGS

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

  • PARTNER_ID
  • DISPLAY_NAME
  • SIGNIN_INTENT_ACTION
  • SIGNIN_INTENT_PACKAGE
  • SIGNIN_INTENT_CLASS
  • SIGNIN_INTENT_FLAGS

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

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

Fire TVのホーム画面ランチャーから、アプリの機能とユーザーの定期購入ステータスに関するリクエストを受けることがあります。Fire TVランチャーがこの情報をリクエストする場合、アクションがcom.amazon.device.REQUEST_CAPABILITIESに指定されたAndroidブロードキャストインテントが使用されます。アプリ側は、 手順A: アプリの機能情報を含むインテントをアプリからブロードキャストするで作成したインテントで応答しなければなりません。

以下の例では、Fire TVランチャーのブロードキャストインテントを処理する簡単なクラスを紹介します。Fire TVランチャーに送信する機能情報は、手順A: アプリの機能情報を含むインテントをアプリからブロードキャストするにおいて送信する情報と同じであるため、両方のタスク管理に同じメソッド(ここではbroadcastCapabilities())を使用することが可能です。

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

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

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

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

どちらの場合も、Fire TVランチャーではbroadcastCapabilities()で指定した情報が使用され、アプリに送信される再生インテントとサインインインテントの両方が構築されます。

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

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

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形式の場合(例:myapp://Media/123456)、Fire TVランチャーはそのURIをインテントデータ(Intent.getData())の一部として送信します。コンテンツIDがURI形式でない場合(例:123456)、Fire TVランチャーはそのIDをbroadcastCapabilities()の一部としてDATA_EXTRA_NAMEで指定したエクストラを使用して送信します。そのコンテンツIDには、Intent.getStringExtra()メソッドを使用してアクセスしてください。

ユーザーが [戻る] ボタンを連続して押した場合(通常はメディア再生画面から3回)、ユーザーがアプリを開いた場所に戻れるようにすることが大切です。今回の場合、Fire TVランチャーの検索結果がそれにあたります。

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

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

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

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

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

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

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

  • 再生インテントとサインインインテントを処理するインテントフィルター
  • Fire TVランチャーがインテントをリクエストできるようにするレシーバー
  • インテントを適切な権限で送信するため権限

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

Fire TVランチャーからインテントを受信するために、再生アクティビティとサインインアクティビティ用のインテントフィルターを追加します。以下の例では、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>

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

マニフェストに実装したBroadcastReceiverクラスの名前でreceiver要素を追加し、アクション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>

権限を追加する

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

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

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

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

(検証のフローについては、手順2: カタログのディープリンクを検証するを参照してください)。

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

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

  • ユーザーがFire TVのユニバーサル検索・閲覧の結果からアプリのコンテンツを選択したら、すぐに再生が開始されるようにします。再生開始前に、ユーザーをアプリのホーム画面やコンテンツの詳細画面に誘導することは避けてください。
  • ランチャー統合の一環として、アプリが開かれるたびにユーザーの定期購入ステータスを発行します。そうすることで、コンテンツがアプリ外で表示された場合でも、定期購入ユーザーに [今すぐ観る] オプションが表示されるようになります。 
  • 現行のカタログ内容が実際に利用可能なコンテンツと一致していない場合に備えて、エラー処理コードを実装します。ユーザーが再生できないコンテンツを選択した場合に、不満を感じないように対処してください。エラー処理コードを実装しないと黒い画面が表示されてしまい、Fire TVやアプリ、カタログなどの画面に戻るのが困難になってしまいます。ユーザーの混乱を招き、ユーザーエクスペリエンスにも悪影響を及ぼしかねません。

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

Q: ユーザーが閲覧・検索を通じてエピソードやシリーズを選択した場合、どのように再生を始めるべきですか?
A: 優れたユーザーエクスペリエンスを提供するために、検索・閲覧の結果からエピソードやシリーズに直接ディープリンクして再生を開始してください。アプリのホーム画面やそのほかの場所にユーザーを誘導することは避けてください。
Q: ユーザーがエピソードやシリーズを選択した際に、どのくらい早く再生を開始すべきですか?
A: 再生開始までにかかる時間は、バッファー処理などの要素の影響でアプリごとに異なりますが、コンテンツが選択された直後に開始するようにしてください。再生開始前にユーザーをアプリのホーム画面やそのほかの場所にリダイレクトすることは避けてください。
Q: 再生が終了したら、どの画面を表示すべきですか?
A: 統合されたカタログからではなく、アプリ経由でコンテンツにアクセスした場合は、ユーザーが期待するであろう画面を表示するようにしてください。アプリによっては、次のエピソードの再生が自動的に開始する場合や、おすすめコンテンツの画面が表示される場合があります。Fire TV経由でコンテンツにアクセスする場合でも、アプリ内でコンテンツにアクセスする場合でも、ユーザーエクスペリエンスの一貫性を保つようにしてください。

次のステップ

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