@amazon-devices/recommendation-manager

The Amazon Media Recommendations API is a service that allows client applications to add and remove recommendations on Amazon devices. These recommendations are displayed on the device's home screen, providing users with personalized content suggestions. The API is designed to enhance the user experience by offering relevant and engaging recommendations based on the user's preferences and viewing history.

The API contains two implementationss of the API:

• RecommendationManager
• RecommendationManager2

Starting with version 2.x.x of the API, new apps should send recommendations using the RecommendationManager2 implementation, which supports content images via content image byte array and content image URI. Old apps are encourage to update to RecommendationManager2 to use its enhanced functionality.

Get started

Permissions

The API requires authentication through the use of privileges. Specifically, the com.amazon.privilege.security.file-sharing privilege is required to access the API for adding recommendations.

Setup

1. Add the following library dependency to the dependencies section of your package.json file.

   Copy code Copied to clipboard.

      "@amazon-devices/recommendation-manager": "~2.0.2"2.
   

2. Add the following privileges in your manifest.toml.

   Copy code Copied to clipboard.

    [wants]
    [[wants.service]]
    id = "com.amazon.recommendation.service.main"
   
    [[needs.privilege]]
    id = "com.amazon.privilege.security.file-sharing"  
   

Usage

Adding Recommendations

1. Create a Recommendation2 object with the required fields (title, text, content image, category, display name, display action option, etc.).
2. Call the addRecommendations2 method of the RecommendationManager2 class, passing an array of Recommendation2 objects.
3. The method returns an array of numbers representing the newly added recommendations. Each number corresponds to a recommendation and can be used for removing the recommendations in the future:
   • If the content image byte array is specified, the image will be stored on the device immediately
   • If the content image URI is specified, the image is downloaded asynchronously. If the image download fails, the recommendation will be removed from the Amazon device and an error message will be logged on the Amazon device indicating that content image URI download failed.

Note: If both content image byte array and content image URI are specified, RecommendationManager2 will default to using content image byte array

Note: The React Native URL constructor automatically appends a trailing / to URLs, which can cause content image URIs to fail downloading. To work around this issue:

1. Create the URL using the standard URL constructor
2. Manually set the _url field to the exact URL string desired

This issue will be addressed in a future version of Recommendation Manager. Note that alternative URL parsing libraries (such as react-native-url-polyfill) are not compatible as Recommendation Manager requires specific fields from the standard URL object.

Example:

Removing Recommendations

1. To remove specific recommendations, call the removeRecommendations() method of the RecommendationManager2 class, passing an array of numbers representing the recommendations to remove.
2. To remove all recommendations sent by the client application, call the removeAllRecommendations() method of the RecommendationManager2 class.

Example:

Legacy Use Cases (Version 1.x.x)

Adding Recommendations

1. Create a Recommendation object with the required fields (title, text, content image, category, display name, display action option, etc.).
2. Call the addRecommendations() method of the RecommendationManager class, passing an array of Recommendation objects.
3. The method returns an array of numbers representing the newly added recommendations. Each number corresponds to a recommendation and can be used for removing the recommendations in the future.

Sample:

Removing Recommendations

1. To remove specific recommendations, call the removeRecommendations() method of the RecommendationManager class, passing an array of numbers representing the recommendations to be removed.
2. To remove all recommendations sent by the client application, call the removeAllRecommendations() method of the RecommendationManager class.

Sample:

Description of recommendation field is as follows

Field	Type	Description	Required
title	string	The content title for the recommendation.	No
text	string	The description text for the recommendation.	No
contentImage	number[]	Image (PNG) to be displayed for this recommendation. Recommendations with incorrect image specifications will cause InvalidArgumentError when calling addRecommendations() method. For details on acceptable image format, see Acceptable image specification.	Yes
contentImageUri	URL	The URI that will be used to retrieve the image (PNG) to be displayed for this recommendation. Recommendations with incorrect image specifications will cause an InvalidArgumentError when calling addRecommendations() method. For details on acceptable image format, see Acceptable image specification.	Yes
backgroundImageUri	URL	The URI that will be used to retrieve the background image for the recommendation. The image appears when user hovers over the recommendation item.	No
contentUri	URL	The URI that will be launched when the user clicks on the recommendation.	No
category	Category	The category the recommendation should go to (For example, Home, Your Videos, Live, UHD).	Yes
displayName	string	A shorter app name displayed in the Launch menu (which appears when you press the menu button while a recommendation is selected).	No
displayActionOption	DisplayAction	Determines the first context menu options displayed for each recommendation.	Yes
maturityRating	string	Displays the maturity rating below the title. For details on acceptable maturity ratings, see Supported maturity rating values.	Yes
customerAggregateRating	number	Aggregate ratings from all customers, possible values range from 0 to 10.	No
customerRatingCount	number	Number of customers who rated this content. If set to 0, content is considered unrated.	No
runningTime	number	The running time (in minutes) for the content, when applicable. Live content can set this to 0.	No
releaseYear	number	The release year for the content. Example: 2016, 2015.	No
isCaptionAvailable	boolean	Indicates whether captions are available for the content (true) or not (false). false means Caption not available for content (default). true means Caption available for content.	No

Acceptable image specification

• Aspect ratio: 16:9
• Channels: 3 (BGR) with 8 bit/channel
• Orientation: Landscape
• Format: PNG
• Depending on display the image resolution should be:
  • HDTV (720p): 256 * 144
  • HDTV (1080p): 384 * 216
  • 4K UHD: 768 * 432
• Title: Embedded within image
• Transparency: No transparency

Supported maturity rating values

• 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

Troubleshooting

• SecurityError: This error occurs when the calling application does not have the required com.amazon.privilege.security.file-sharing privilege. Make sure that your application has the necessary privileges before you make calls to the API.
• InvalidArgumentError: This error can occur in the following scenarios:
  • The size of a recommendation object exceeds 512KB (excluding the content image size).
  • Mandatory fields in the Recommendation object are empty or invalid.
  • The content image does not meet the specified dimensions and size requirements.
  • The size of the recommendations array passed to addRecommendations() is greater than 20.

• In cases where recommendations aren't showing up:

  • Check whehter the images failed to download if content image URI flow was used. If image download failed, the recommendation will not be added. Device logs will indicate that the image download failed. For example:

    Failed to fetch image for recommendation. Ignoring it.
    

  • Check if the recommendation was successfully added to the Recommendation Manager database using the unique row id. The unique row id can be found in the logs:

    recommendation_[4509]: 8 I recommendationCommonLib:[log_impl.cpp:14] Recommendations are for config: <unique-row-id>
    

    After finding the unique-row-id, check config file corresponding to the unique row id above. This file contains the recommendations that have been successfully added to the row. If this file is empty, that means the calling application's recommendations weren't added. Please check device logs for error logs when calling addRecommendations.

    Copy code Copied to clipboard.

    adb shell cat /home/app_user_packages/com.amazon.recommendation.service/data/<unique-row-id>
    

Modules

• index
• RecommendationManager
• RecommendationManager2
• turbo-modules/RecommendationManagerTurboModule
• turbo-modules/RecommendationManagerTurboModule
• types/RecommendationManagerTypes
• types/RecommendationManagerTypes

---

Last updated: Sep 30, 2025