@amazon-devices/recommendation-manager

The Amazon Media Recommendations API is a service that allows client apps to add and remove recommendations on Amazon devices. The API displays the recommendations 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 implementations:

• RecommendationManager
• RecommendationManager2

Starting with version 2.x.x of the API, new apps should send recommendations using the RecommendationManager2 implementation. The implementation supports content images via content image byte array and content image URI. You are encouraged to update old apps to RecommendationManager2 to use it's enhanced functionality.

Get started

Permissions

The API requires authentication through the use of privileges. Specifically, an app requires com.amazon.privilege.security.file-sharing privilege 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 is used to remove the recommendations in the future:
   • If you specify the content image byte array, the image is stored on the device immediately
   • If you speicfy the content image URI, the image is downloaded asynchronously. If the image download fails, the recommendation is removed and an error message is logged that indicates that the content image URI download failed.

Note: If you specify a both content image byte array and a content image URI, RecommendationManager2 defaults to the content image byte array.

Note: The React Native URL constructor automatically appends a trailing / to URLs. This 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 app, call the removeAllRecommendations() method of the RecommendationManager2 class.

Example:

Legacy Use Cases (Version 1.x.x)

Adding legcacy 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 which that the can use to remove the recommendations in the future.

Sample:

Removing legacy recommendations

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

Sample:

The 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 display for this recommendation. Recommendations with incorrect image specifications return an InvalidArgumentError when calling the addRecommendations() method. For details on acceptable image formats, see Acceptable image specification.	Yes
contentImageUri	URL	The URI to use to retrieve the image (PNG) to display for this recommendation. Recommendations with incorrect image specifications return an InvalidArgumentError when calling addRecommendations() method. For details on acceptable image format, see Acceptable image specification.	Yes
backgroundImageUri	URL	The URI to use to retrieve the background image for the recommendation. The image appears when the user hovers over the recommendation item.	No
contentUri	URL	The URI to launch 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 to display 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 the 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 app does not have the required com.amazon.privilege.security.file-sharing privilege. Make sure that your app 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:

  • If you used that content image URI, check whether the images failed to download . If the image download failed, the recommendation isn't added. Device logs will show 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. You can find 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 you find the unique-row-id, check the config file corresponding to the unique row ID. The file contains the recommendations that have been successfully added to the row. If the file is empty, that means the calling app's recommendations weren't added. 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: Nov 17, 2025