Managing Recommendations (Fire TV)
This section explains how to create and manage Recommendations for Partner Managed Row (PMR).
- Creating Recommendations
- Sending Recommendations at Boot-Up
- Deleting 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
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
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.
|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|
We recommend using below specifications for the large icon image:
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.
|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
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.
|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|
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.
|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
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:
- The app is installed and the user is authenticated. Do not wait for a device reboot.
- After a device reboot.
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