Developer Console

Recommendations Overview (Fire TV)

Your app can send recommendations to users about the content (movies, shows, music, games) that you want them to watch. Recommendations appear on a "Recommended By Your Apps" row on the Amazon Fire TV home screen.

Recommendations encourage users to engage with your app. By appearing on the Fire TV home screen, recommendations are visible within the user's regular view. The recommendation cards entice users back into your app with minimal effort.

For more information about recommendations, see Recommending TV Content in the Android documentation. The Android TV Leanback Support Library app also contains sample code for sending recommendations.

Note that recommendations are not supported on Fire TV Stick Basic Edition.

Where Recommendations Appear

On the Amazon Fire TV home screen, the "Recommended By Your Apps" row shows all recommendations from apps the user has currently installed (and opened at least once).

All recommendations from third-party apps appear as visually attractive cards in this row. You control the look and appearance of the recommendation cards.

Recommendations are sorted by a selection algorithm provided by Fire TV. The row refreshes regularly.

How the Recommendations Row Works

If you select a recommendation and then click the Menu button on your remote, a launch menu appears in the lower-right corner. The menu shows different viewing options.

The text shown in the launch menu — "Open" — might differ across recommendations. Depending on the string set by the app, a recommendation can show any of the following strings:

  • Watch
  • Resume
  • Switch Profile
  • Change Settings
  • View
  • Play
  • Listen
  • Open

If a user selects "Open TED TV" instead of "Watch," the TED TV app will launch (instead of the selected content). Selecting this option is the same as launching an app the normal way on Amazon Fire TV.

Additionally, you can control your app's name in this launch menu by setting the value for DISPLAY_NAME, which is an Amazon extra in your recommendation.

Recommendations Attributes

The following image shows the various attributes of the recommendations row.

The attributes are as follows:

Title of recommendation provided by the app
Name of the app that sent the recommendation
Description of the recommendation provided by the app
Image of the recommendation provided by the app
Operations available for the recommended media. (Press the Menu button on Fire TV remote to bring up this menu.)

Requirements for Recommendations to Appear

The following two requirements must be met for recommendations to appear:

  • There must be at least 5 recommendations in total sent from all apps.
  • The user can't have any viewing restrictions set under Settings > Preferences > Parental Controls.

Note that Android limits the number of notifications to 50. This limit includes both standard notifications and recommendations combined.

What to Recommend

Recommendations should show content that is relevant to the user. For example, recommendations might present the following:

  • New episodes for shows the user watched earlier
  • Similar shows related to the user's viewing history
  • Content with similar tags as other shows the user has watched

You will need to create the logic that determines which recommendations are shown to which users.

Make sure the content you recommend is appropriate for the audience. See Best Practices for Recommendations for more details.

Send Recommendations

You can send recommendations by following the approach described in the Android documentation. See these Android topics:

In general, you build a service that looks at your app's content and suggests recommendations. You send the recommendations as notification objects, tagged with a recommendation category and configured with the values you want. You also register the service with your app's manifest.

When you define the recommendations, you set the foreground and background image, color, app icon, title, subtitle, and more. See Recommendation Row in Google's Android TV for more design and UX details with recommendations.

You can group your recommendations using the NotificationCompat.Builder.setGroup() method.

For more details on creating recommendations, see Send Recommendations that Include Amazon Extras.

Amazon's Extensions to Android Recommendations

Amazon extends the Android recommendations API to provide deeper integration with Amazon Fire TV. Note that using Amazon's extras is optional. If you don't use the extras, your recommendations will still work on Fire TV. However, you will lose out on some Fire TV-specific features.

The Amazon extensions won't affect the display of your recommendations on other Android TV platforms.


Can I view metrics to see clicks on recommendations from the Fire TV home screen?
You can add an extra to the pending intent. This will allow you to capture the origin of where the link was clicked.
Can users turn recommendations off?
No. Although users can turn notifications off for specific apps, they cannot turn recommendations off.

For more background reading on recommendations, see Android TV Recommendations: What's in it for my app or game?.

Next steps

To learn more, see the following:

Last updated: Oct 29, 2020