Developer Console

Best Practices & FAQ (Fire TV)

This section covers best practices and frequently-asked questions for Partner Managed Rows (PMR).

Best Practices

  • Do Not Crank Up the Priority Level – Many applications seem to be using higher priority values than specified by the official documentation. We use EXTRA_AMAZON_RANK. If not present, then we shall use recommendation recency to determine the sort position. If present, the items will be sorted first by rank in ascending order and then by time of submission with most recent first.
  • Do Not Keep Stale Cards Around – Make sure your content is still relevant, and remove old or stale cards. Further, don't instantiate 'already stale' cards, make sure you track to some degree what content has been shown (and visited) before. For example, if the user finished watching the recommended content, you may want to remove that specific item using instructions to remove recommendations mentioned above.

    If you don't follow these recommendations, the user may manually turn off your recommendations completely; in the worst case, the user might be so frustrated that they will go the faster route and simply uninstall your application, and potentially leave a negative rating on the Amazon Appstore.

  • Android's 50 Notifications Limit – Android enforces a limit of maximum of 50 notifications for each package. This includes recommendations and any other notifications the app intends to use. (See the MAX_PACKAGE_NOTIFICATIONS definition in NotificationServiceManager.) So please make sure to cancel older notifications before sending new notifications (if the number exceeds 50). Otherwise, you may see log errors such as: W/NotificationManager﹕ notify: id corrupted: sent 51, got back 0.
  • Personalization – Recommendations are most effective when they are personalized based on the interest, profile and recent activity of the user within your application along with other parameters. The user may find personalized recommendations more effective and engaging than general recommendations.
  • Limit the Number of Recommendations Thrown at One Time – We would recommend not to send many recommendations at once. Please consider batching recommendations together in smaller groups of around 5 at a time. The minimum number of recommendations for PMR to display is 5. This requirement is to make sure Fire TV UI looks consistent.
  • Sending Recommendation as a Background App– Possible trigger points for sending recommendations are scheduling AlarmManager at repeating interval(s) and on expiry schedule an Android JobScheduler job or Syncadapter tasks.
  • In Event of Your Application Signature Change – We are using application signature to check the validity of recommendation sender. If you intend to change the application signature in the future, please contact Amazon developer portal. Also, please follow the standard operating procedure around application update submission with the Amazon Appstore. Please use the release signature and package name as your production application for development which may involve side-loading the application.
  • Handling Back Button Events – If your app is capturing the Back button event, do not send the intent to navigate to Fire TV Home and instead exit the application upon handling the last back button event within your app. This will allow the user to navigate back to the PMR row.

FAQ

PMR Row Is Missing Following a Reboot
The UI does not update the contents of the PMR row while the user has navigated to a specific category. Traversing from the Home section, for example, to some other section such as Movies or TV Shows (and back again) will force a UI update. The PMR will then reflect recommendations emitted by your app since boot.

PMR Row Is Missing Following an OTA Update
Server API call Time-To-Live (TTL) is 5 hours. To force a refresh, please follow these steps:

  1. Go to Settings.
  2. Select My Account.
  3. Click Sync Amazon Content.
  4. The recommendation row shall now show up under Home and/or Your Videos sections.

Enabling the Developer Row
The Developer Row helps app developers in testing their recommendations on a sample PMR row. Developers can test the look and feel of their recommendations as they will be shown on Fire TV. Developer Row is available starting Fire OS 5.2.4.0 release on Gen-2 Fire TV and Gen-2 Fire TV Stick.

To enable the Developer Row, please follow these steps:

  1. Open Developer Tools menu by holding SELECT + D-PAD DOWN buttons for 3 seconds and then press MENU on Fire TV Remote. Similarly, on Amazon Game Controllers, hold A + Y for 3 seconds and then press MENU button.

  2. Turn ON the Developer Options.

  3. Turn ON the Developer Row. All installed application packages will appear in a list view. To test your recommendations in the sample PMR row, select your package name.

  4. Press OK.

  5. Reboot the device.

Resources

PMR References

PMR API Guide


Last updated: Oct 29, 2020