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

The following table lists extras that you can add to your PreviewProgram object.

Extra name Data type Details

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.

com.amazon.extra.ACTION_OPTION int Determines the context menu options displayed for each recommendation. One context menu action is supported and 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_OPTION are as follows:

1: Watch with <App name>
2: Watch
3: Resume with <App name>
4: Resume
5: Switch <App name> Profile
6: Change <App name> Settings
7: Change Settings
8: View with <App name>
9: View
10: Play with <App name>
11: Play
12: Listen with <App name>
13: Listen

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

com.amazon.extra.CONTENT_CAPTION_AVAILABILITY int Caption availability of content:
0: Caption not available for content.
1: Caption available for content.

Extra name	Data type	Details
`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.
`com.amazon.extra.ACTION_OPTION`	int	Determines the context menu options displayed for each recommendation. One context menu action is supported and 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_OPTION` are as follows: 1: Watch with `<App name>` 2: Watch 3: Resume with `<App name>` 4: Resume 5: Switch `<App name>` Profile 6: Change `<App name>` Settings 7: Change Settings 8: View with `<App name>` 9: View 10: Play with `<App name>` 11: Play 12: Listen with `<App name>` 13: Listen If no value is provided, the default action will be Open and below that, Launch `<App name>`.
`com.amazon.extra.CONTENT_CAPTION_AVAILABILITY`	int	Caption availability of content: `0`: Caption not available for content. `1`: Caption available for content.

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.

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.

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:

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