Developer Console
Sign In
Sign In
Developer Console

Partner-Managed Row (Fire TV)

You submit recommendations to a Partner Managed Row (PMR) by using Android notifications. Amazon provides expanded functionality by using extra fields in the notification.

PMR on Android TV

The Android framework allows applications to submit recommendations by using Android notifications. In API level 21 and above, notifications may be tagged with a special recommendation category. You create a standard Android notification and set the category to Notification.CATEGORY_RECOMMENDATION.

Note that Android imposes a limit of 50 notifications active for at one time for any app. This includes notifications categorized as recommendations.

PMR Amazon Enhancements for Fire TV

Notifications and recommendations are submitted through the same mechanism on standard Android devices and Fire TV devices. Amazon's local recommendation mechanism is built on the standard Android ContentRecommendation.Builder API.

Expanded functionality is available through extras. Developers can add the following extra values to their Notification object.

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

Sample Recommendation Card

The following sample recommendation card shows how fields are displayed on the card.

The callout numbers on the card refer to the following fields:

  1. Title
  2. Text
  3. ContentImage
  4. Display Name (com.amazon.extra.DISPLAY_NAME)

    Depending on which tag(s) you associate with the recommendation, the button display label will vary:
    CategoryButton display label
    HomeWatch Now with <DISPLAY_NAME>
    Your VideosWatch Now with <DISPLAY_NAME>

Last updated: Mar 26, 2021