Developer Console

Managing Recommendations (Fire TV)

This section explains how to create and manage Recommendations for Partner Managed Row (PMR).

Creating Recommendations

This section explains how to create Recommendations using the App Recommendation Support Library for TV. Prior to creating recommendations, you must add the support library to the dependencies block of your project's build.gradle file.

ContentRecommendation API Example

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

// Sets an ID for the notification, so it can be updated
int notifyID = int_value;

ContentRecommendation rec = new ContentRecommendation.Builder()
        .setContentImage(myBitmap)
        .setBackgroundImageUri(myBackgroundImageUri)
        .setContentIntentData(ContentRecommendation.INTENT_TYPE_***, mIntent, mRequestCode, mBundle)
        .setText(mText)
        .setTitle(mTitle)
        .setBadgeIcon(R.drawable.<app_icon>)
        .setGenres(mGenres)
        .setContentTypes(mTypes)
        .setProgress(mMaxLength,mProgress)
        .setRunningTime(contentLength)
        .build();

Notification notification = rec.getNotificationObject(mContext);

// The additional extra values get added as follows:

// Assign a business name for the partner which may be shown on the UI
notification.extras.putString("com.amazon.extra.DISPLAY_NAME", mDisplayName);

// Assign a maturity rating to this recommendation
notification.extras.putString("com.amazon.extra.MATURITY_RATING", mMaturityRating);

// Assign a category to this recommendation.
ArrayList<String> tagList = new ArrayList<String>();
tagList.add(Home);
tagList.add("Your Videos");
notification.extras.putStringArrayList("com.amazon.extra.TAGS", tagList);

// Specifies where a recommendation should be displayed in the list
notification.extras.putInt("com.amazon.extra.RANK", mRank);

// Assign a long description to this recommendation
notification.extras.putString("com.amazon.extra.LONG_DESCRIPTION", mLongDescription);

// Assign a catalog integration content ID to this recommendation
notification.extras.putString("com.amazon.extra.CONTENT_ID", mContentID);

// Assign a last watched time to this recommendation
notification.extras.putLong("com.amazon.extra.LAST_WATCHED_DATETIME", mLastWatchedTime);

// Assign a preview video or image URL of this recommendation
notification.extras.putString("com.amazon.extra.PREVIEW_URL", mPreviewUrl);

// Assign an action to this recommendation.
ArrayList<Integer> actionList = new ArrayList<Integer>();
actionList.add(1);
actionList.add(3);
notification.extras.putIntegerArrayList(com.amazon.extra.ACTIONS, actionList);

// Assign a Live Content to this recommendation.
notification.extras.putInt(com.amazon.extra.LIVE_CONTENT, 1);

// Assign Release date to this recommendation
notification.extras.putString(com.amazon.extra.CONTENT_RELEASE_DATE, "2016");

// Assign Caption availability to this recommendation
notification.extras.putInt(com.amazon.extra.CONTENT_CAPTION_AVAILABILITY, 1);

// Assign an IMDB ID to this recommendation
notification.extras.putString(com.amazon.extra.IMDB_ID, "fc145d345xxxxxxxx");

// Assign an IMDB rating to this recommendation
notification.extras.putString(com.amazon.extra.IMDB_SCORE, "6.2");

// Assign a start time of live content to this recommendation
notification.extras.putLong(com.amazon.extra.CONTENT_START_TIME, System.currentTimeMillis());

// Assign a end time of live content to this recommendation
notification.extras.putLong(com.amazon.extra.CONTENT_END_TIME, System.currentTimeMillis() + 10000);

mNotificationManager.notify(notifyID, notification);

Refer to the Android documentation for more information on setContentIntentData().

While you can create the recommendations in a way similar to the code snippet above, following are the attributes that shall help integrate seamlessly with the Fire TV look and feel.

The numbers mentioned in the table refer to the callouts displayed on the following card.

API Behavior Change Required
setTitle(java.lang.String) Shall be displayed in (1) above. The length limit is 125 or else it shall be truncated. Yes
setText(java.lang.String) Shall be displayed in (2) above. The length limit is 125 or else it shall be truncated. Yes
setContentImage(Bitmap image) We recommend using below specifications for the large icon image:
  • Height: 252px or more
  • We recommend keeping an overall aspect ratio of 16:9
  • Embedding text (title) to image fetches better user engagement
  • Must not be transparent
If the large icon is not present, we may place a default placeholder instead.

Shall be displayed in (3) above.

For future proofing, asset aspect ratio should be configurable on the server, making the client agnostic to image resolution. Future release may require 16:9.
Yes
setContentIntentData(int intentType, Intent intent, int requestCode, Bundle options) Sets the data for the Intent that will be issued when the user clicks on the recommendation. The Intent data fields provided correspond to the fields passed into the PendingIntent factory methods, when creating a new PendingIntent. The actual PengindIntent object will only be created at the time a recommendation is posted to the Home Screen. Yes
setBadgeIcon(int iconResourceId) Sets the resource ID for the recommendation badging icon.

The resource id represents the icon resource in the source application package. If not set, or an invalid resource ID is specified, the application icon retrieved from its package will be used by default.
Yes
setGenres(String[] genres) Sets the content genres for the recommendation. These genres may be used for content ranking. Genres are open ended String tags. We recommend using the standard Genres defined by Android. No
setContentTypes(String[] types) Sets the content types associated with the content recommendation. The first tag entry will be considered the priority type for the content and will be used for ranking purposes. Other secondary type tags may be provided, if applicable, and may be used for filtering purposes. Only standard Android content recommendation categories are allowed. No
setProgress(int max, int progress) Sets the progress information for the content pointed to by the recommendation. The progress amount for the content must be in the range (0 - max) seconds. No
setBackgroundImageUri(String imageUri) Sets the Content URI that will be used to retrieve the background image for the recommendation.

The background image should be in 16:9 format. It should not be taller than 1080px and no wider than 1920px. For best performance, background image should be 960px wide x 540px tall.
Yes
setRunningTime(long length) Sets the running time (when applicable) for the content associated with the notification. No

Catalog and Launcher Integration Requirements

If you have an integrated catalog, your PMR can provide deeper integration. Note that some content (such as live streams) is not catalog-integrated.

Check the integration with Fire TV launcher guide for deep-linking. This provides access to the partner (application's) subscription status, which is needed by Fire TV launcher to enable recommendations.

Fire TV partners with login/subscription requirement need to broadcast their subscription status so that launcher shows the right hint for the application content. This helps to avoid any user confusion, and also enables PMR content to get deep-linked with the app without showing the login page. For this reason, the system displays the PMR for an app only when the user has a subscription for that app.

Sending Recommendations at Boot-Up

If you plan to send recommendations when the device boots up, you need to make sure your application is allowed to receive and handle the broadcast that tells the application that your device was booted. To enable this capability, add this permission as a child of the element to your Android Manifest:

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

Once you have that, the initial launch point for supporting recommendations is to create a subclass of BroadcastReceiver. In the manifest, you then register the receiver as handling the ACTION_BOOT_COMPLETED intent. This ensures that when the system first boots up, all applications that are interested get an initial 'ping' to generate their recommendations. For this to work reliably, please make sure that your application is not installed on the external storage. Please refer to App install location and android:installLocation manifest attribute links for more details.

In addition, it is important that you also send recommendations in response to the following events:

  1. The app is installed and the user is authenticated. Do not wait for a device reboot.
  2. After a device reboot.

Deleting Recommendations

You may call cancel() for a specific notification ID to delete the recommendation:

NotificationManager notificationManager = (NotificationManager) sContext.getSystemService(NOTIFICATION_SERVICE);

// Use the same notification id which you used while creating this notification
notificationManager.cancel(notifyID);

Last updated: Oct 29, 2020