開発者コンソール

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エクストラは通知オブジェクトに追加されます。メソッドやエクストラ(mTextmContextなど)に渡される値は、コードの別の場所に配置されます(スペースの関係で、この部分のコードは表示されていません)。 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 14におけるおすすめの送信

Android 14を搭載したデバイスを追加するには、以下のガイダンスに従っておすすめを送信します。

互換性の確認

ホーム画面では、Fire OSのバージョンに応じて、次の2つの方法でアプリからのおすすめを表示できます。

Fire OSのすべてのバージョンでおすすめが表示されるようにするには、両方のおすすめAPIを実装します。現在のシステムのAPIレベルをテストし、適切なAPIを使用しておすすめを作成してください。

if (android.os.Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
  // Android 14のおすすめガイドを使用します
} else {
  // Fire OS 7のおすすめガイドを使用します
}

TVProviderを使用したおすすめの送信

Android 14では、Android TVのおすすめライブラリ(TVProvider)を使用して、[ダウンロード済みアプリからのおすすめ] 行におすすめを送信します。おすすめの送信に関する詳細については、AndroidドキュメントのChannels on the home screenChannelクラス、PreviewProgramクラスを参照してください。

Android 14でのおすすめのコード例

おすすめを作成するには、次の2つの手順を実行する必要があります。

  1. おすすめチャネルを作成する
  2. チャネルIDを使用してチャネルにおすすめを送信する
手順1: おすすめチャネルを作成する
  1. Channel.Builderを作成して属性を設定します。
  2. プロバイダーにチャネルを挿入します。
  3. 後でチャネルに番組を追加できるように、チャネルIDを保存します。
Channel.Builder builder = new Channel.Builder();
// 作成するチャネルのタイプはすべてTYPE_PREVIEWである必要があります
builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
        .setDisplayName("チャネル名")
        
        
 Uri channelUri = context.getContentResolver().insert(
        TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues());
       
 // このチャネルIDを保存しておくと、後でチャネルを更新する際や
 // 番組を追加する際に使用できます
 long channelId = ContentUris.parseId(channelUri);
val builder = Channel.Builder()
// 作成するチャネルのタイプはすべてTYPE_PREVIEWである必要があります
builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
    .setDisplayName("チャネル名")

val channelUri = context.contentResolver.insert(
    TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues()
)

// このチャネルIDを保存しておくと、後でチャネルを更新する際や
// 番組を追加する際に使用できます
val channelId = ContentUris.parseId(channelUri)
手順2: チャネルにおすすめを送信する
  1. PreviewProgram.Builderを作成して属性を設定します。
  2. プロバイダーに番組を挿入します。
  3. 必要に応じて、後で参照できるように番組IDを取得します。
// その他のオプションのAmazonエクストラ値を以下のように追加します

// バンドルを作成します
Bundle bundle = new Bundle();
bundle.putInt("com.amazon.extra.CONTENT_CAPTION_AVAILABILITY", 1);
bundle.putString("com.amazon.extra.DISPLAY_NAME", "display_name");
bundle.putInt("com.amazon.extra.ACTION_OPTION", 1);

// バンドルをバイト配列(Blob)に変換します
Parcel parcel = Parcel.obtain();
bundle.writeToParcel(parcel, 0);
byte[] extrasBlob = parcel.marshall();
parcel.recycle(); // 使用したパーセルをリサイクルします

// おすすめを送信します
PreviewProgram.Builder builder = new PreviewProgram.Builder();
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_MOVIE)
        .setTitle("タイトル")
        .setDescription("番組の説明")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderData(extrasBlob);
        
Uri programUri = context.getContentResolver().insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
      builder.build().toContentValues());
      
// この番組IDは後で番組を更新する際に使用できます
long programId = ContentUris.parseId(programUri);
// その他のオプションのAmazonエクストラ値を以下のように追加します

// バンドルを作成します
val extras = Bundle().apply {
    putInt("com.amazon.extra.CONTENT_CAPTION_AVAILABILITY", 1)
    putString("com.amazon.extra.DISPLAY_NAME", "display_name");
    putInt("com.amazon.extra.ACTION_OPTION", 1)
}
 
// バンドルをバイト配列(Blob)に変換します
 val parcel = Parcel.obtain()
bundle.writeToParcel(parcel, 0)
val extrasBlob = parcel.marshall()
parcel.recycle() // 使用したパーセルをリサイクルします

val builder = PreviewProgram.Builder()
    .setChannelId(channelId)
    .setType(TvContractCompat.PreviewPrograms.TYPE_MOVIE)
    .setTitle("タイトル")
    .setDescription("番組の説明")
    .setPosterArtUri(uri)
    .setIntentUri(uri)
    .setInternalProviderData(extrasBlob)

val programUri = context.contentResolver.insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
    builder.build().toContentValues()) 

// この番組IDは後で番組を更新する際に使用できます
val programId = ContentUris.parseId(programUri)

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

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

API 説明 必須
setTitle(java.lang.String title) おすすめのコンテンツタイトルを設定します。最大文字数は125文字です。それ以上のテキストは切り捨てられます。 はい
setDescription(java.lang.String description) おすすめの概要テキストを設定します。最大文字数は125文字です。それ以上のテキストは切り捨てられます。 はい
setThumbnailUri(Uri thumbnailUri) おすすめの画像を設定します。大きなアイコン画像の仕様は次のとおりです。

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

画像のないおすすめの場合、表示されないか、代わりにデフォルトのプレースホルダーが適用されます。縦横比が16:9以外の画像はレターボックス化されます(レターボックス化とは、左右または上部を黒く表示して空白スペースができないようにすることです)。 指定のサイズより大きな画像は、スペースに合うように縮小され、16:9の縦横比は維持されます。
はい
setContentRatings(TvContentRating contentRatings[]) タイトルの下に評価が表示されます。この評価は、コンテンツの再生にPINの入力が必要かどうかを判定する、Amazon Fire TVの機能制限の設定にも使用されます。この値を含まないおすすめは、成人向けコンテンツとみなされ、デバイスの機能制限の設定でPINの入力が必要になる場合があります。現在サポートされている値については、TvContentRatingを参照してください。 いいえ
setReleaseDate(java.lang.String releaseDate)

setReleaseDate(java.util.Date releaseDate)
コンテンツのリリース年を設定します。 いいえ
setReviewRating(java.lang.String reviewRating) ユーザーによる評価。有効な値は0~10の範囲です。 いいえ
setIntentUri(Uri intentUri) おすすめが選択されたときに起動されるインテントのURIを設定します。 いいえ
setPosterArtUri(Uri posterArtUri) おすすめの背景画像のURLを設定します。 いいえ
setStartTimeUtcMillis(long startTime) コンテンツの実行時間(該当する場合)を設定するために使用されます。 いいえ
setEndTimeUtcMillis(long endTime) コンテンツの実行時間(該当する場合)を設定するために使用されます。 いいえ

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

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

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

エクストラの名前 データ型 詳細
com.amazon.extra.DISPLAY_NAME 文字列 (おすすめを選択した状態でメニューボタンを押した場合に)起動メニューに表示されるアプリの略称。最大文字数は15文字です。それ以上の文字は切り捨てられ、省略記号で表示されることもありません。
com.amazon.extra.ACTION_OPTION int 各おすすめに表示されるコンテキストメニューオプションを決定します。1つのコンテキストメニューアクションのみがサポートされ、構成可能です。ユーザーがおすすめのタイルまたは1つ目のコンテキストメニューオプションをクリックすると、Amazon Fire TVは、おすすめと共に渡された、対応するコンテンツのインテントデータを使用して、アプリを起動します。注: アプリがアクションのArrayListを提供している場合は、com.amazon.extra.DISPLAY_NAME(上記)が必要です。ACTION_OPTIONに指定できる値は次のとおりです。

1: <アプリ名>で観る
2: 観る
3: <アプリ名>で続きを観る
4: 続きを観る
5: <アプリ名>のプロフィールを切り替え
6: <アプリ名>の設定を変更
7: 設定を変更
8: <アプリ名>で観る
9: 観る
10: <アプリ名>で再生
11: 再生
12: <アプリ名>で聞く
13: 聞く

値が指定されていない場合、デフォルトのアクションは「開く」になり、その次が「<アプリ名>を起動」となります。
com.amazon.extra.CONTENT_CAPTION_AVAILABILITY int コンテンツのクローズドキャプションの可否。
0: クローズドキャプション非対応
1: クローズドキャプション対応

マニフェストを構成

デバイスの起動時におすすめを送信するには、アプリに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を参照してください。

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

おすすめの削除

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

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

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

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

次のステップ

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


Last updated: 2025年1月17日