Customize the recommendations with Amazon extras
Amazon allows you to send extra values with your recommendations. These extras allow you to customize your recommendations to better fit the Fire TV platform. You can read about the Amazon extras in the general Fire TV documentation here: Send Recommendations that Include Amazon Extras.
Currently, some of the Amazon extras you can send aren't currently used by Fire TV. (They may be used in the future, though.) In other cases, Fire App Builder sends a default value (which you can't change) for the Amazon extra.
- Amazon Extras
- How to Submit Amazon Extras in Fire App Builder
- How to Include Extras in Your Fire App Builder Recommendations
- Customizing the App Display Name in Recommendations
- Next Steps
Amazon Extras
The following table lists the Amazon extras available. This list is the same list of Amazon Extras as in Fire TV. Following the list is a section that explains how to submit Amazon Extras in Fire App Builder.
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.
Currently, supported values are as follows:
|
Yes |
com.amazon.extra.ACTION_OPTION |
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 |
Yes |
com.amazon.extra.RANK |
int | This extra is used to sort items in ascending order by rank, after which they are subsorted by time of submission (most recent first). If absent, time of submission is used alone. Possible values range from 0 to INTEGER.MAX_VALUE . The lower the value, the higher the rank; that is, low values appear ahead of high values |
No |
com.amazon.extra.CONTENT_ID |
String | This id corresponds to the content id used in Catalog Integration. | No |
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:
| 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.
| 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 |
How to Submit Amazon Extras in Fire App Builder
The following table describes how Fire App Builder handles each tag, how to map Amazon extra elements in your feed to Fire App Builder's content model tags, and any special notes about data types. For most Amazon Extra tags, you use your contents recipe to map elements in your feed to these tag names.
contents recipe1
0
Extra name | How to use in Fire App Builder |
---|---|
com.amazon.extra.DISPLAY_NAME |
Instead of mapping a DISPLAY_NAME in each feed item, you set this value in your app's strings.xml file. See Customizing the App Display Name in Recommendations for details. |
com.amazon.extra.MATURITY_RATING |
Map to the tag maturityRating in your contents recipe. |
com.amazon.extra.RANK |
Not available to change. Fire App Builder sends a rank of 0 (the highest priority) for every content item. |
com.amazon.extra.ACTION_OPTION |
Fire App Builder sends an empty list and accepts the defaults from Fire TV. By default, Fire TV will use the terms Open and Launch <App Name> in the launch context menu. To customize what Fire App Builder sends, map to the tag actions in your contents recipe. Note: If your app is providing an action array list, the com.amazon.extra.DISPLAY_NAME (mentioned above) is required. |
com.amazon.extra.LIVE_CONTENT |
Map this element to the tag live in your contents recipe. Also, note that the value for live must be a Boolean (true or false ) rather than an integer of 0 or 1 (the Fire TV extras require the integer data type). Fire App Builder will actually convert the Boolean to an integer when sending the recommendation. For more details, see Configure Live Streams. If your content is live, the "Watch from Beginning" button will be omitted from the media playback screen. |
com.amazon.extra.CONTENT_RELEASE_DATE |
Map to the tag availableDate in your contents recipe. |
com.amazon.extra.CONTENT_CAPTION_AVAILABILITY |
<td">Content caption availability will be automatically detected if the content has it. You don't need to map this element in your . If your content has closed caption availability, Fire App Builder passes a when sending the recommendation. If not, it passes . </td>
|
com.amazon.extra.IMDB_ID |
Map to the tag imdbId in your contents recipe. |
com.amazon.extra.CONTENT_START_TIME |
Map to the tag startTime in your contents recipe. Only valid for live content. |
com.amazon.extra.CONTENT_END_TIME |
Map to the tag endTime in your contents recipe. Only valid for live content. |
com.amazon.extra.TEXT_EMBEDDED_IMAGE |
Not supported |
com.amazon.extra.LONG_DESCRIPTION |
Fire App Builder passes the regular description to this extra. |
com.amazon.extra.LAST_WATCHED_DATETIME |
Fire App Builder automatically picks up this value by looking at the records in its database for the content. Fire App Builder stores the last time every content is watched. There's no need to map this value in your contents recipe. |
com.amazon.extra.PREVIEW_URL |
Map to the tag videoPreviewUrl in your contents recipe. |
genres |
genres isn't an Amazon extra — it's part of the regular Android recommendations API. Map this element to the tag genres in your contents recipe. genres should point to an array of strings, not a single string. For example: "genres": ["COMEDY", "ARTS", "EDUCATION"] . Use the standard Android genre terms. |
How to Include Extras in Your Fire App Builder Recommendations
You include the extras with the item details in your feed (but not inside the recommendations
tag — the recommendations
tag should simply list an array of content IDs). When Fire App Builder builds the related recommendations, any additional information matching the Amazon extras will also be included.
Here's an example of an item in a feed that includes all the extras:
{
"id": "162270",
"title": "Thai Recipes - Thai Chicken Noodles Recipe",
"description": "Thai Recipes - Thai Chicken Noodles Recipe",
"duration": "355",
"thumbURL": "http://l2.cdn01.net/_thumbs/0000162/0162270/0162270__015f" type="jpg",
"imgURL": "http://l2.cdn01.net\/_thumbs/0000162/0162270/0162270__015f" type="jpg",
"videoURL": "http://media.cdn01.net/802E1F/process/encoded/video_1880k/0000162/0162270/D8HFLX0AC.mp4?source=firetv&channel_id=6341",
"categories": [
"International Cuisine"
],
"channel_id": "6341",
"recommendations": [
"162269",
"162266",
"162265",
"162264"
],
"maturityRating": "PG",
"live": true,
"startTime": 1490393748,
"endTime": 1490397347,
"videoPreviewUrl": "http://mywebsite.com/some/url/to/the/video.mp4",
"imdbId": "tt2417148",
"genres": ["DRAMA"],
"actions": [1, 101]
}
In your contents recipe, you map these extras in the same way you map your other feed properties but without the m
. For example:
{
"cooker": "DynamicParser",
"format": "json",
"model": "com.amazon.android.model.content.Content",
"translator": "ContentTranslator",
"modelType": "array",
"query": "$.items[?(@.categories[0] in [$$par0$$])]",
"matchList": [
"title@mTitle",
"id@mId",
"description@mDescription",
"videoURL@mUrl",
"imgURL@mCardImageUrl",
"imgURL@mBackgroundImageUrl",
"channel_id@mChannelId",
"recommendations@mRecommendations",
"maturityRating@maturityRating",
"live@live",
"startTime@startTime",
"endTime@endTime",
"videoPreviewUrl@videoPreviewUrl",
"imdbId@imdbId",
"genres@genres",
"actions@actions"
]
}
On the left of the @
symbol you put the property's name in your feed; on the right of the @
symbol you put the value for Fire App Builder's content model. The names to map are listed in the previous table.
Customizing the App Display Name in Recommendations
In the recommendation's display on the Fire TV home screen, Fire TV truncates your app title after 15 characters. This may cause your app name to look odd. For example, "Fire App Builder" gets truncated to "Fire App Builde."
To set a shorter title for the 15-character recommendation space, you can customize the display name. Here's an example of a customized name:
To customize your app name in the recommendation details:
-
Open your app's strings.xml file (inside res > values > strings.xml).
Note that strings.xml is separated out into multiple files depending on the language you're targeting. For US English, use strings.xml (en).
-
In this file, add the following element with the app name you want:
<string name="app_name_short">FireAppBuilder</string>
When Fire App Builder builds the recommendation, it will use the value included here and pass it as the com.amazon.extra.DISPLAY_NAME
.
Next Steps
You've completed all the steps to build and configure your app. When you're ready, Submit Your App to the Appstore.
Last updated: Apr 06, 2017