Developer Console
Sign In
Sign In
Developer Console

Customize the recommendations with Amazon extras

 V: Add Recommendations

STEP 1:
Recommendations Overview
→
STEP 2:
Send Global Recommendations
→
STEP 3:
Send Related Recommendations
→
STEP 4:
Customize 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

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:

  • US Marketplace: G, PG, PG13, R, NC17, NR, TVY, TVY7, TVG, TVPG, TV14, TVMA
  • German Marketplace: FSK0, FSK6, FSK12, FSK16, FSK18
  • Great Britain Marketplace: BBFCPG, BBFC12, BBFC18, BBFCU
  • Japan Marketplace: EIRIN_G, EIRIN_PG12, EIRIN_R15, EIRIN_18
  • India Marketplace:ALL, 7+, 13+, 16+, 18+, NR
 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 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.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:
  • 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

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 recipe10 <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>
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
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:

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

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