Send Recommendations that Include Amazon Extras (Amazon Fire TV)
You create recommendations by creating
ContentRecommendation objects through the
ContentRecommendation.Builder() class. In addition to the attributes in this class, you can also include Amazon-specific extras to better integrate with Amazon Fire TV.
- Creating Recommendations
- Sample Recommendation
- Code Example for a Recommendation
- Recommended Attributes for Android API code
- Amazon Enhancements to Recommendations
- Configuring the Manifest
- Delete Recommendations
- Next steps
Amazon’s recommendations use the standard Android
ContentRecommendation.Builder API. For full details, see the Android documentation on Recommending TV Content and the
In addition what’s included in the Android documentation, you can expand the recommendations functionality in your notification objects with Amazon-specific extras. These extras help integrate the recommendations into Amazon Fire TV in deeper ways.
Before diving into code examples, let’s look at a sample recommendation card. The numbers show several attributes set through the Android API and one attribute set through an Amazon extra.
setText. Sets the description for the recommendation. (Android API)
setContentImage. Sets the image used for the recommendation. (Android API)
Sets an abbreviated name for your app, which is used in the launch menu. This is set by one of the Amazon extra fields:
For example, if your app has a long name, such as “World Premier Association Videos for Fire TV,” this long title will be truncated in the launch menu. Instead of accepting the default truncation, you can specify the shortened name for your app through the Amazon extras (in this case, the
The following screenshot shows how the AOL On app customized the text in the launch menu using Amazon
Code Example for a Recommendation
dependenciesblock of your app’s build.gradle file.
The following code shows how to create a
ContentRecommendation object and
getNotificationObject that includes Amazon extras:
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) // From API 23 this method also accepts Icon as argument. .setBackgroundImageUri(myBackgroundImageUri) .setContentIntentData(ContentRecommendation.INTENT_TYPE_, mIntent, mRequestCode, mBundle) // For more information on setContentIntentData(), see 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) // This method won't have any influence on ratings on Fire TV. Use the com.amazon.extra.MATURITY_RATING setting instead. .setRunningTime(contentLength) .build(); Notification notification = rec.getNotificationObject(mContext); //The additional Amazon extra values get added as follows: //Assign a business name for the application 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); //Specifies how recommendations from one app is ordered. 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 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 the UHD tag to put your recommendation on the 4K UHD row ArrayList<String> tagList = new ArrayList<String>(); tagList.add("UHD"); notification.extras.putStringArrayList("com.amazon.extra.TAGS", tagList); //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 a customer rating to this recommendation notification.extras.putInt(com.amazon.extra.CONTENT_CUSTOMER_RATING, 5); //Assign a customer rating count to this recommendation notification.extras.putInt(com.amazon.extra.CONTENT_CUSTOMER_RATING_COUNT, 10); //Assign a imdbid to this recommendation notification.extras.putString(com.amazon.extra.IMDB_ID, "tt0417148"); //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);
The Amazon extras are added to the notification object. The values passed to the methods and extras (such as
mContext are assumed to be set elsewhere in the code. (For the sake of space, this part of the code isn’t shown.) More information for using the Android recommendations API and Amazon extras are provided in the following sections.
Recommended Attributes for Android API code
Follow these guidelines when using the ContentRecommendation.Builder from the Android API. These guidelines will help your recommendations align with the look and feel of Amazon Fire TV.
||"Sets the content title for the recommendation."
The length limit is 125 characters. Additional text is truncated.
||"Sets the description text for the recommendation."
The length limit is 125 characters. Additional text is truncated.
||"Sets the recommendation image."
Use the following specifications for the large icon image:
Recommendations without images either won't be displayed or will receive a default placeholder instead. Images with an aspect ratio other than 16:9 will be letterboxed. (Letterboxing means black bars will appear along the sides or top to compensate for the empty space.) Images larger than the specified dimensions will be scaled down to fit the space, preserving the 16:9 aspect ratio.
||"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
||"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|
||"Sets the content genres for the recommendation. These genres may be used for content ranking. Genres are open ended String tags. Some examples: 'comedy', 'action', 'dance', 'electronica', 'racing', etc."
Use the standard Android genres.
||"Sets the content types associated with the content recommendation. The first tag entry will be considered the primary 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.
||"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). The unit is seconds.
||"Sets the Content URI that will be used to retrieve the background image for the recommendation."
A 960px wide x 540px tall image (aspect ratio 16:9) is required. Note: Recommendations with an aspect ratio other than 16:9 will be dropped. Larger images will be scaled down to fit the space, but note that the image size cannot be taller than 1080px or wider than 1920px.
||"Sets the running time (when applicable) for the content."||Yes|
Amazon Enhancements to Recommendations
The following table lists extras that you can add to your notification objects.
|Extra name||Data type||Details||Used|
||String||A shorter app name displayed in the Launch menu (which appears when you press the menu button while a recommendation is selected). The length limit is 15 characters. Additional characters are truncated without showing an ellipses for the truncated characters.||Yes|
||String||Displays the rating below the title. The rating is also used by the Parental Control settings on Amazon Fire TV to determine if content playback needs to be behind a PIN. Any recommendation without this extra or without a value for
Currently, supported values are as follows:
||ArrayList<int>||Determines the context menu options displayed for each recommendation. Two context menu actions are supported, but only the first action is configurable.
When users click a recommendation tile or its first context menu option, Amazon Fire TV uses the corresponding content intent data passed with recommendation to launch the app. Note: If your app is providing an action array list, the
Possible values to include for the
If no value is provided, the default action will be
||int||Helps determine whether a recommendation is live content and needs to be displayed or hidden based on ||No|
||String||Content release year. Example: 2016, 2015, 1977 etc.||Yes|
||int||Caption availability of content.
||String||IMDB ID of content. (For example, if the URL is
||long||Start time of live content in milliseconds (EPOCH).||No|
||long||End time of live content in milliseconds (EPOCH).||No|
||String||Long description of a recommendation. Length is limited to 512 characters.||No|
||long||Last watched time of the recommended content in milliseconds (EPOCH).||No|
||String||Preview video or image URL for the recommendation.||No|
||ArrayList<String>||If your content is 4K (Ultra HD), add the tag
||int||Customer rating, possible values range from 0 to 10.||Yes|
||int||Number of customers rated this content.||Yes|
Configuring the Manifest
To send recommendations when the device boots up, your app must have the
RECEIVE_BOOT_COMPLETED permission. This permission lets your app receive and handle the broadcast that tells the app your device was booted.
To receive the broadcast, add the following permission (to your Android Manifest) as a child of the
The initial launch point for supporting recommendations is to create a subclass of
BroadcastReceiver. In the manifest, register the receiver as handling the
ACTION_BOOT_COMPLETED intent. When the system first boots up, all applications that are interested will get an initial ‘ping’ to generate their recommendations. For more details, see this How to Start an Application at Device Bootup in Android tutorial on Stacktips.com.
For the broadcast to work reliably, make sure your app is not installed on external storage. Refer to the following for more details about storage locations:
- Specifying Your App’s Installation Location
- App install location
- android:installLocation manifest attribute
As a best practice, delete recommendations after users watch the recommended content. You can call cancel() for a specific notification ID to delete the recommendation.
The following code sample shows how to delete recommendations:
Notification notification = rec.getNotificationObject(mContext); //Use the same notification id which you used while creating this notification notification.cancel(notifyID);
To learn more, see the following: