Amazonエクストラを含むおすすめを送信する


Amazonエクストラを含むおすすめを送信する

おすすめを作成するには、ContentRecommendationオブジェクトをContentRecommendation.Builder()クラスを使用して作成します。このクラスの属性と併せてAmazon固有のエクストラを指定すると、Amazon Fire TVとの連携を高めることができます。

おすすめの作成

Amazonのおすすめ機能では、標準のAndroidContentRecommendation.Builder APIを実装します。詳細については、Android関連ドキュメントのTVコンテンツのおすすめContentRecommendation.Builderクラスを参照してください。

Androidドキュメントで取り上げられている内容に加えて、Amazon固有のエクストラを通知オブジェクトに追加することで、おすすめ機能を拡張することができます。エクストラは、Amazon Fire TVのおすすめ表示を強化する働きをします。

おすすめのサンプル

コードの例に入る前に、おすすめ画面のサンプルを見てみましょう。各番号は属性を示しています。Android APIを使用して設定された属性が複数、Amazonエクストラによる属性が1つあります。

setTitle。おすすめのタイトルを設定します(Android API)
setText。おすすめの概要を設定します(Android API)
setContentImage。おすすめに使用する画像を設定します(Android API)
起動メニューに表示されるアプリの略称を設定します。この設定には、Amazon extraフィールドを使用します。com.amazon.extra.DISPLAY_NAME", "displayName"

たとえば、アプリの名前が「World Premier Association Videos for Fire TV」のように長い場合、短縮して起動メニューに表示することができます。Amazonエクストラを使用すると、デフォルトの切り捨てではなく、アプリの略称を指定できます(この例では、DISPLAY_NAMEです)。

下のスクリーンショットは、Amazon extraフィールドによってカスタマイズされた、AOL Onアプリの起動メニューのテキスト表示を示しています。

おすすめのコード例

次のコードは、Amazonエクストラを含むContentRecommendationオブジェクトとgetNotificationObjectの作成方法を示しています。

mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
//通知のIDを設定して、更新できるようにします
int notifyID = int_value;

ContentRecommendation rec = new ContentRecommendation.Builder()
        .setContentImage(myBitmap) // API 23から、このメソッドは引数としてアイコンも受け取ります。
        .setContentIntentData(ContentRecommendation.INTENT_TYPE_, mIntent, mRequestCode, mBundle) // setContentIntentData()の詳細については、https://developer.android.com/reference/android/support/app/recommendation/ContentRecommendation.htmlを参照してください
        .setText(mText)
        .setTitle(mTitle)
        .setBadgeIcon(R.drawable.<app_icon>)
        .setGenres(mGenres)
        .setContentTypes(mTypes)
        .setProgress(mMaxLength,mProgress)
        .setMaturityRating(mMaturityRating) // このメソッドはFire TVの評価に一切影響しません。代わりに、com.amazon.extra.MATURITY_RATING設定を使用します。
        .setRunningTime(contentLength)
        .build();


Notification notification = rec.getNotificationObject(mContext);

//別のAmazon extra値が次のように追加されました:

//UIに表示される可能性があるアプリの通称を指定します
notification.extras.putString("com.amazon.extra.DISPLAY_NAME", mDisplayName);

//このおすすめに成人向けコンテンツ評価を割り当てます
notification.extras.putString("com.amazon.extra.MATURITY_RATING", mMaturityRating);

//1つのアプリからのおすすめの並べ方を指定します。
notification.extras.putInt("com.amazon.extra.RANK", mRank);

//このおすすめに詳しい説明を割り当てます
notification.extras.putString("com.amazon.extra.LONG_DESCRIPTION", mLongDescription);

//このおすすめに最終視聴時刻を割り当てます
notification.extras.putLong("com.amazon.extra.LAST_WATCHED_DATETIME", mLastWatchedTime);

//このおすすめにプレビュービデオ・画像のURLを割り当てます
notification.extras.putString("com.amazon.extra.PREVIEW_URL", mPreviewUrl);

//4K UHDの行におすすめを配置するためのUHDタグを割り当てます
ArrayList<String> tagList = new ArrayList<String>();
tagList.add("UHD");
notification.extras.putStringArrayList("com.amazon.extra.TAGS", tagList);

//このおすすめにライブコンテンツを割り当てます。
notification.extras.putInt(com.amazon.extra.LIVE_CONTENT, 1);

//このおすすめにリリース日を割り当てます
notification.extras.putString(com.amazon.extra.CONTENT_RELEASE_DATE, "2016");

//このおすすめにクローズドキャプション対応の有無を割り当てます
notification.extras.putInt(com.amazon.extra.CONTENT_CAPTION_AVAILABILITY, 1);

//このおすすめにユーザーによる評価を割り当てます
notification.extras.putInt(com.amazon.extra.CONTENT_CUSTOMER_RATING, 5);

//このおすすめにユーザーによる評価の数を割り当てます
notification.extras.putInt(com.amazon.extra.CONTENT_CUSTOMER_RATING_COUNT, 10);

//このおすすめにIMDb IDを割り当てます
notification.extras.putString(com.amazon.extra.IMDB_ID, "tt0417148");

//このおすすめにライブコンテンツの開始時刻を割り当てます
notification.extras.putLong(com.amazon.extra.CONTENT_START_TIME, System.currentTimeMillis());

//このおすすめにライブコンテンツの終了時刻を割り当てます
notification.extras.putLong(com.amazon.extra.CONTENT_END_TIME, System.currentTimeMillis() + 10000);

mNotificationManager.notify(notifyID, notification);

Amazonエクストラは通知オブジェクトに追加されます。メソッドやエクストラ(mTextmContextなど)に渡される値は、コードの別の場所に配置されます(スペースの関係で、この部分のコードは表示されていません)。 Android recommendations APIとAmazonエクストラについては、次のセクションで詳しく説明します。

Android APIコードで推奨される属性

Android APIのContentRecommendation.Builderを使用する際はこのガイドラインに従ってください。Amazon Fire TVのルック&フィールに沿ったおすすめを作成できます。

API 説明 必須
setTitle(java.lang.String) 「おすすめのコンテンツタイトルを設定します。」

最大文字数は125文字です。それ以上のテキストは切り捨てられます。

あり
setText(java.lang.String) 「おすすめの概要テキストを設定します。」

最大文字数は125文字です。それ以上のテキストは切り捨てられます。

あり
setContentImageBitmap画像 「おすすめの画像を設定します。」

大きなアイコン画像の仕様は次のとおりです。

  • サイズ: 高さ252ピクセル以上
  • 縦横比: 16:9
  • タイトル: 画像内に埋め込み
  • 透明性: 不透明

画像のないおすすめの場合、表示されないか、代わりにデフォルトのプレースホルダーが適用されます。縦横比が16:9以外の画像はレターボックス化されます(レターボックス化とは、両サイドまたは上部分を黒く表示して空白スペースができないようにすることです)。 指定のサイズより大きな画像は、スペースに合うように縮小され、16:9の縦横比は維持されます。

あり
setContentIntentData(int intentType, Intent intent, int requestCode, Bundle options) 「ユーザーがおすすめをクリックしたときに発行されるインテントのデータを設定します。新しいPendingIntentを作成する際に、提供されるインテントデータのフィールドがPendingIntentファクトリメソッドに渡されるフィールドに対応します。実際のPendingIntentオブジェクトは、おすすめがホーム画面に送信されるときにのみ作成されます。」 あり
setBadgeIcon(int iconResourceId) 「おすすめのバッジアイコンのリソースIDを設定します。リソースIDは、ソースとなるアプリパッケージのアイコンリソースを表します。この設定を行わない場合、またはリソースIDが無効な場合、パッケージから取得されるアプリアイコンがデフォルトとして使用されます。」 あり
setGenres(String[] genres) 「おすすめのコンテンツジャンルを設定します。ジャンルは、コンテンツランキングに使用される場合があります。ジャンルは、制約のない文字列タグです。例:'comedy'、'action'、'dance'、'electronica'、'racing'など。」

標準のAndroidジャンルを使用します。

なし
setContentTypes(String[] types) 「おすすめに関連するコンテンツタイプを設定します。最初に入力されるタグが、コンテンツの主要なタイプとみなされ、ランキングに使用されます。必要に応じて、そのほかの二次的タイプも入力できます。このタグはフィルタリングに使用される場合があります」。

Androidの標準的なコンテンツおすすめカテゴリーのみ使用できます。

なし
setProgress(int max、int progress) 「おすすめで参照されるコンテンツの進行状況情報を設定します。」

コンテンツの進行状況を指定の範囲(0~最大値)で表示する必要があります。この単位は秒です。

なし
setRunningTime(long length) 「コンテンツの実行時間(該当する場合)を設定します。」 あり

おすすめ機能に対するAmazonエクストラ

次の表は、通知オブジェクトに追加できるエクストラを示しています。

エクストラの名前 データ型 詳細 使用
com.amazon.extra.DISPLAY_NAME String (おすすめを選択しているときにメニューボタンを押すと)起動メニューにアプリの略称が表示されます。最大文字数は15文字です。それ以上の文字は切り捨てられ、省略記号で表示されることもありません。 あり
com.amazon.extra.MATURITY_RATING String タイトルの下に評価が表示されます。この評価は、Amazon Fire TVの機能制限の設定にも使用され、コンテンツの再生にPINの入力が必要かどうかを判定します。このエクストラまたはsetMaturityRating()の値を含まないおすすめは、成人向けコンテンツとみなされます。したがって、デバイスのペアレンタルコントロール設定によっては、PINが必要になる場合があります。

現時点でサポートされている値は次のとおりです。

  • 米国のマーケットプレイス: GPGPG13RNC17NRTVYTVY7TVGTVPGTV14TVMA
  • ドイツのマーケットプレイス: FSK0FSK6FSK12FSK16FSK18
  • 英国のマーケットプレイス: BBFCPGBBFC12BBFC18BBFCU
  • 日本のマーケットプレイス: EIRIN_GEIRIN_PG12EIRIN_R15EIRIN_18
  • インドのマーケットプレイス:ALL7+13+16+18+NR
あり
com.amazon.extra.ACTION_OPTION ArrayList<int> 各おすすめに表示されるコンテキストメニューオプションを決定します。コンテキストメニューでは2つのアクションがサポートされていますが、1つめのアクションのみ設定可能です。

ユーザーがおすすめのタイルまたは1つ目のコンテキストメニューオプションをクリックすると、Amazon Fire TVがおすすめと共に渡された対応するコンテンツインテントデータを使用して、アプリが起動されます。注: アプリがアクションのArrayListを提供しているときは、com.amazon.extra.DISPLAY_NAME(上記)が必要です。

次の値をACTION_OPTIONに含むことができます。

  • 1<App name>で観る
  • 101: Watch
  • 2<App name>で続きを観る
  • 102: Resume
  • 3<App name>のプロフィールを切り替え
  • 4<App name>の設定を変更
  • 104: Change Settings
  • 5<App name>で観る
  • 105: View
  • 6<App name>で再生
  • 106: Play
  • 7<App name>で聞く
  • 107: Listen

値が指定されていない場合、デフォルトのアクションはOpenとなり、その下は「<App Name>を起動」となります。

あり
com.amazon.extra.LIVE_CONTENT int おすすめがライブコンテンツでCONTENT_START_TIMECONTENT_END_TIMEに基づいて表示または非表示にする必要があるかどうかを判断します。サポートされる値は次のとおりです。
  • 0: ライブコンテンツではない
  • 1: ライブコンテンツ
なし
com.amazon.extra.CONTENT_RELEASE_DATE String コンテンツのリリース年。例: 2016、2015、1977など。 あり
com.amazon.extra.CONTENT_CAPTION_AVAILABILITY int コンテンツのクローズドキャプション対応の有無。
  • 0: クローズドキャプション非対応
  • 1: クローズドキャプション対応
あり
com.amazon.extra.IMDB_ID String コンテンツのIMDb ID(たとえば、URLがhttp://www.imdb.com/title/tt0417148の場合、IDはtt0417148です)。 なし
com.amazon.extra.CONTENT_START_TIME long ライブコンテンツのミリ秒単位での開始時刻(エポック) なし
com.amazon.extra.CONTENT_END_TIME long ライブコンテンツのミリ秒単位での終了時刻(エポック) なし
com.amazon.extra.LONG_DESCRIPTION String おすすめの概要。最大512文字です。 なし
com.amazon.extra.LAST_WATCHED_DATETIME long おすすめコンテンツのミリ秒単位での最終視聴時刻(エポック)。 なし
com.amazon.extra.PREVIEW_URL String おすすめのプレビュービデオ・画像のURL。 なし
com.amazon.extra.TAGS ArrayList<String> コンテンツが4K(Ultra HD)の場合に、タグ ["UHD"] であることを確認する。 あり
com.amazon.extra.CONTENT_CUSTOMER_RATING int ユーザーによる評価。有効な値は0~10の範囲です。 あり
com.amazon.extra.CONTENT_CUSTOMER_RATING_COUNT int このコンテンツを評価したユーザーの数。 あり

マニフェストを構成

デバイスの起動時におすすめを送信するには、アプリにRECEIVE_BOOT_COMPLETEDパーミッションが必要です。このパーミッションにより、アプリは、デバイスが起動したことを通知するブロードキャストを受け取り処理することができます。

ブロードキャストを受け取るには、<manifest>要素の子として(Androidマニフェストに)次のパーミッションを追加します。

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

おすすめをサポートするためにまず取りかかることは、BroadcastReceiverのサブクラスの作成です。マニフェストでは、ACTION_BOOT_COMPLETEDインテントを処理するレシーバーを登録します。システムの初回起動時に、関連のあるすべてのアプリがおすすめを生成するための最初の「ping」を取得します。詳細については、Stacktips.comのチュートリアルHow to Start an Application at Device Bootup in Android(Androidデバイスの起動時にアプリを起動する方法)を参照してください。

ブロードキャストを正しく機能させるため、アプリが外部ストレージにインストールされていないことを確認してください。ストレージ場所の詳細については以下を参照してください。

おすすめの削除

ベストプラクティスとして、ユーザーが視聴したおすすめコンテンツは削除するようにしてください。特定の通知IDに対応するcancel()を呼び出すことで、該当のおすすめを削除できます。

次のコード例は、おすすめを削除する方法を示しています。

mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);

//この通知を作成したときと同じ通知IDを使用
mNotificationManager.cancel(notifyID);

次のステップ

詳細については、以下を参照してください。