Send Recommendations that Include Amazon Extras

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.

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.

Sample Recommendation

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.

setTitle. Sets the title for the recommendation. (Android API)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: com.amazon.extra.DISPLAY_NAME", "displayName".

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 DISPLAY_NAME).

The following screenshot shows how the AOL On app customized the text in the launch menu using Amazon extra fields.

Code Example for a Recommendation

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 updatedintnotifyID=int_value;ContentRecommendationrec=newContentRecommendation.Builder().setContentImage(myBitmap)// From API 23 this method also accepts Icon as argument..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();Notificationnotification=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 UInotification.extras.putString("com.amazon.extra.DISPLAY_NAME",mDisplayName);//Assign a Maturity rating to this recommendationnotification.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 recommendationnotification.extras.putString("com.amazon.extra.LONG_DESCRIPTION",mLongDescription);//Assign a last watched time to this recommendationnotification.extras.putLong("com.amazon.extra.LAST_WATCHED_DATETIME",mLastWatchedTime);//Assign a preview video or image URL of this recommendationnotification.extras.putString("com.amazon.extra.PREVIEW_URL",mPreviewUrl);//Assign the UHD tag to put your recommendation on the 4K UHD rowArrayList<String>tagList=newArrayList<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 recommendationnotification.extras.putString(com.amazon.extra.CONTENT_RELEASE_DATE,"2016");//Assign Caption availability to this recommendationnotification.extras.putInt(com.amazon.extra.CONTENT_CAPTION_AVAILABILITY,1);//Assign a customer rating to this recommendationnotification.extras.putInt(com.amazon.extra.CONTENT_CUSTOMER_RATING,5);//Assign a customer rating count to this recommendationnotification.extras.putInt(com.amazon.extra.CONTENT_CUSTOMER_RATING_COUNT,10);//Assign a imdbid to this recommendationnotification.extras.putString(com.amazon.extra.IMDB_ID,"tt0417148");//Assign a start time of live content to this recommendationnotification.extras.putLong(com.amazon.extra.CONTENT_START_TIME,System.currentTimeMillis());//Assign a end time of live content to this recommendationnotification.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 mText or 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.

Note: Because the descriptions of these standard Android API methods are from the Android documentation, they're set off in quotes to distinguish them from any additional notes we have added.

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 PendingIntent object will only be created at the time a recommendation is posted to the Home Screen."

"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."

"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."

"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."

Amazon Enhancements to Recommendations

The following table lists extras that you can add to your notification objects.

Note: "Used" (the column on the far right) indicates whether Amazon Fire TV currently makes use of this data in the Fire TV recommendations display on the home screen. Even if an extra isn't used now, it may be used in the future with upcoming Fire TV releases.

Extra name

Data type

Details

Used

com.amazon.extra.DISPLAY_NAME

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

com.amazon.extra.MATURITY_RATING

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 setMaturityRating() will be treated as Mature content and may require a PIN subject to the Parental Control settings on the device.

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 com.amazon.extra.DISPLAY_NAME (mentioned above) is required.

Possible values to include for the ACTION_OPTIONare as follows:

1: Watch with <App name>

101: Watch

2: Resume with <App name>

102: Resume

3: Switch <App name> Profile

4: Change <App name> Settings

104: Change Settings

5: View with <App name>

105: View

6: Play with <App name>

106: Play

7: Listen with <App name>

107: Listen

If no value is provided, the default action will be Open and below that, Launch <App Name>.

Yes

com.amazon.extra.LIVE_CONTENT

int

Helps determine whether a recommendation is live content and needs to be displayed or hidden based on CONTENT_START_TIME and CONTENT_END_TIME. Supported values are as follows:

0: Not a Live content

1: Live Content

No

com.amazon.extra.CONTENT_RELEASE_DATE

String

Content release year. Example: 2016, 2015, 1977 etc.

Yes

com.amazon.extra.CONTENT_CAPTION_AVAILABILITY

int

Caption availability of content.

0: Caption not available for content

1: Caption available for content

Yes

com.amazon.extra.IMDB_ID

String

IMDB ID of content. (For example, if the URL is http://www.imdb.com/title/tt0417148, the ID is tt0417148.)

No

com.amazon.extra.CONTENT_START_TIME

long

Start time of live content in milliseconds (EPOCH).

No

com.amazon.extra.CONTENT_END_TIME

long

End time of live content in milliseconds (EPOCH).

No

com.amazon.extra.LONG_DESCRIPTION

String

Long description of a recommendation. Length is limited to 512 characters.

No

com.amazon.extra.LAST_WATCHED_DATETIME

long

Last watched time of the recommended content in milliseconds (EPOCH).

No

com.amazon.extra.PREVIEW_URL

String

Preview video or image URL for the recommendation.

No

com.amazon.extra.TAGS

ArrayList<String>

If your content is 4K (Ultra HD), add the tag ["UHD"].

Yes

com.amazon.extra.CONTENT_CUSTOMER_RATING

int

Customer rating, possible values range from 0 to 10.

Yes

com.amazon.extra.CONTENT_CUSTOMER_RATING_COUNT

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 <manifest> element:

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:

Delete Recommendations

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:

mNotificationManager=(NotificationManager)getSystemService(Context.NOTIFICATION_SERVICE);//Use the same notification id which you used while creating this notificationmNotificationManager.cancel(notifyID);