開発者コンソール
ログイン
ログイン
開発者コンソール

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

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

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

このプロセスの手順については、次のビデオ（日本語字幕付き）で説明しています。詳細については、本ページの残りの部分を参照してください。

おすすめの作成

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

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

おすすめのサンプル

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

setTitle。おすすめのタイトルを設定します（Android API）
setText。おすすめの概要を設定します（Android API）
setContentImage。おすすめに使用する画像を設定します（Android API）
起動メニューに表示されるアプリの略称を設定します。この設定には、次のAmazonエクストラフィールドを使用します。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エクストラは通知オブジェクトに追加されます。メソッドやエクストラ（mText、mContextなど）に渡される値は、コードの別の場所に配置されます（スペースの関係で、この部分のコードは表示されていません）。 Android recommendations APIとAmazonエクストラについては、次のセクションで詳しく説明します。

Fire OS 7における推奨事項

Android 8.0（APIレベル26）では、アプリが送信する通知をチャネルに割り当てる必要があります（「おすすめ」は通知の一種です）。 アプリが通知またはおすすめを送信する場合、チャネルを作成し、そのチャネルを通知に関連付ける必要があります。チャネルIDがない通知は破棄されます。

通知にチャネルを追加する手順の概要は、以下のとおりです。

  1. 手順1： 通知チャネルを作成し、通知マネージャーに渡して登録する
  2. 手順2： 通知のチャネルIDを設定する（次のいずれかの方法を使用します）

以下のセクションでは、上記の内容について詳しく説明すると共に、コードサンプルを示します。

手順1： 通知チャネルを作成し、通知マネージャーに渡して登録する

以下は、Androidドキュメントの通知チャネルを作成するからの抜粋です。

通知チャネルを作成する

通知チャネルを作成する手順は次のとおりです。

  1. 固有のチャネルID、ユーザーに表示される名前、重要度を指定して、NotificationChannelオブジェクトを作成します。
  2. 必要であれば、システム設定でユーザーに表示される説明をsetDescriptionで指定します。

  3. createNotificationChannelに通知チャネルを渡して登録します。

    private void createNotificationChannel() {
    //NotificationChannelを作成しますが、API 26以降でのみ使用します。
    //これは、NotificationChannelクラスが新しく、サポートライブラリにないためです
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        CharSequence name = getString(R.string.channel_name);
        String description = getString(R.string.channel_description);
        int importance = NotificationManager.IMPORTANCE_DEFAULT;
        NotificationChannel channel = new NotificationChannel(CHANNEL_ID, name, importance);
        channel.setDescription(description);
        //チャネルをシステムに登録します。この後で重要度や
        //通知動作を変更することはできません
        NotificationManager notificationManager = getSystemService(NotificationManager.class);
        notificationManager.createNotificationChannel(channel);
    }
}

手順2： 通知のチャネルIDを設定する

通知のチャネルIDを設定する方法には、2つのオプションがあります。ContentRecommendationとリフレクションを使用するオプションと、Notification.Builderを使用するオプションです。

オプション1： createContentRecommendationとリフレクションを使用してチャネルIDを設定する

Notification notification = createContentRecommendation(largeIcon, notificationId);

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    Log.d(TAG, "SDKバージョンはAndroid O以上です");

    try {
        Field channel = notification.getClass().getDeclaredField("mChannelId");
        channel.setAccessible(true);
        channel.set(notification, StringTerms.CHANNEL_ID);
    }
    catch (Exception e) {
        Log.d(TAG, "チャネルIDを設定できません", e);
    }
}

オプション2： Notification.BuilderとチャネルIDを使用する

以下のコードは、Google Gitで公開されているAndroidオープンソースプロジェクトのコードを適宜変更したものです。

public Notification getNotificationObject(Context context) {
    Notification.Builder builder = new Notification.Builder(context, "channelId");
    RecommendationExtender recExtender = new RecommendationExtender();

    //通知オブジェクト内にあるすべてのおすすめコンテンツデータをエンコードします

    builder.setCategory(Notification.CATEGORY_RECOMMENDATION);
    builder.setContentTitle(mTitle);
    builder.setContentText(mText);
    builder.setContentInfo(mSourceName);
    builder.setLargeIcon(mContentImage);
    builder.setSmallIcon(mBadgeIconId);
    if (mBackgroundImageUri != null) {
        builder.getExtras().putString(Notification.EXTRA_BACKGROUND_IMAGE_URI, mBackgroundImageUri);
    }
    builder.setColor(mColor);
    builder.setGroup(mGroup);
    builder.setSortKey(mSortKey);
    builder.setProgress(mProgressMax, mProgressAmount, false);
    builder.setAutoCancel(mAutoDismiss);

    if (mContentIntentData != null) {
        PendingIntent contentPending;
        if (mContentIntentData.mType == INTENT_TYPE_ACTIVITY) {
            contentPending = PendingIntent.getActivity(context, mContentIntentData.mRequestCode,
            mContentIntentData.mIntent, PendingIntent.FLAG_UPDATE_CURRENT,
            mContentIntentData.mOptions);
        }
        else if (mContentIntentData.mType == INTENT_TYPE_SERVICE) {
            contentPending = PendingIntent.getService(context, mContentIntentData.mRequestCode,
            mContentIntentData.mIntent, PendingIntent.FLAG_UPDATE_CURRENT);
            }
            else { // Default:INTENT_TYPE_BROADCAST{
            contentPending = PendingIntent.getBroadcast(context,
            mContentIntentData.mRequestCode,
            mContentIntentData.mIntent, PendingIntent.FLAG_UPDATE_CURRENT);
            }
        builder.setContentIntent(contentPending);
    }

    if (mDismissIntentData != null) {
        PendingIntent dismissPending;
        if (mDismissIntentData.mType == INTENT_TYPE_ACTIVITY) {
            dismissPending = PendingIntent.getActivity(context, mDismissIntentData.mRequestCode,
            mDismissIntentData.mIntent, PendingIntent.FLAG_UPDATE_CURRENT,
            mDismissIntentData.mOptions);
        }
        else if (mDismissIntentData.mType == INTENT_TYPE_SERVICE) {
            dismissPending = PendingIntent.getService(context, mDismissIntentData.mRequestCode,
            mDismissIntentData.mIntent, PendingIntent.FLAG_UPDATE_CURRENT);
            }
            else { // Default:INTENT_TYPE_BROADCAST{
                dismissPending = PendingIntent.getBroadcast(context,
                mDismissIntentData.mRequestCode,
                mDismissIntentData.mIntent, PendingIntent.FLAG_UPDATE_CURRENT);
            }
        builder.setDeleteIntent(dismissPending);
    }

    recExtender.setContentTypes(mContentTypes);
    recExtender.setGenres(mContentGenres);
    recExtender.setPricingInformation(mPriceType, mPriceValue);
    recExtender.setStatus(mStatus);
    recExtender.setMaturityRating(mMaturityRating);
    recExtender.setRunningTime(mRunningTime);

    builder.extend(recExtender);
    Notification notif = builder.build();
    return notif;
}

詳細については、Androidドキュメントの通知チャネルを作成して管理するを参照してください。

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

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

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

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

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

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

 はい
setContentImage（Bitmap画像） 「おすすめの画像を設定します。」

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

  • サイズ： 高さ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 タイトルの下に評価が表示されます。この評価は、コンテンツの再生にPINの入力が必要かどうかを判定する、Amazon Fire TVの機能制限の設定にも使用されます。このエクストラまたはsetMaturityRating()の値を含まないおすすめは、成人向けコンテンツとみなされ、デバイスの機能制限の設定でPINの入力が必要になる場合があります。

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

  • 米国のマーケットプレイス： G、PG、PG13、R、NC17、NR、TVY、TVY7、TVG、TVPG、TV14、TVMA
  • ドイツのマーケットプレイス： FSK0、FSK6、FSK12、FSK16、FSK18
  • 英国のマーケットプレイス： BBFCPG、BBFC12、BBFC18、BBFCU
  • 日本のマーケットプレイス： EIRIN_G、EIRIN_PG12、EIRIN_R15、EIRIN_18
  • インドのマーケットプレイス：ALL、7+、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： <アプリ名>で今すぐ観る
  • 101： Watch
  • 2： <アプリ名>で続きを観る
  • 102： Resume
  • 3： <アプリ名>のプロフィールを切り替え
  • 4： <アプリ名>の設定を変更
  • 104： Change Settings
  • 5： <アプリ名>で観る
  • 105： View
  • 6： <アプリ名>で再生
  • 106： Play
  • 7： <アプリ名>で聞く
  • 107： Listen

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

 あり
com.amazon.extra.RANK int このエクストラはアイテムをランクを条件に昇順でソートするために使用されます。ソート後は、送信時刻によって（最新のものから順に）サブソートされます。指定されていない場合、送信時刻が単独で使用されます。指定できる値の範囲は、0～INTEGER.MAX_VALUEです。値が小さいほどランクが高くなります。つまり、小さい値は大きい値より先に表示されます。 なし
com.amazon.extra.CONTENT_ID String このIDは、カタログ統合で使用されるコンテンツIDに対応します。 なし
com.amazon.extra.LIVE_CONTENT int おすすめがライブコンテンツかどうか、また、CONTENT_START_TIMEおよびCONTENT_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);

次のステップ

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