@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

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

"@amazon-devices/recommendation-manager": "~2.0.8".

Add the following privileges in your manifest.toml.

    [wants]
    [[wants.service]]
    id = "com.amazon.recommendation.service.main"

    [[needs.privilege]]
    id = "com.amazon.privilege.security.file-sharing"

Usage

Adding Recommendations

Create a Recommendation2 object with the required fields (title, text, content image, category, display name, display action option, etc.).
Call the addRecommendations2 method of the RecommendationManager2 class, passing an array of Recommendation2 objects.
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:

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

const imageUrl = new URL('https://example.com/image.png');
(imageUrl as any)._url = 'https://example.com/image.png';  // Remove trailing slash

// In Recommendation2 object
contentImageUri: imageUrl

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:

import {
    RecommendationManager2,
    Recommendation2,
    Category,
    DisplayAction,
    InvalidArgumentError,
    SecurityError,
} from '@amazon-devices/recommendation-manager';

const recommendationWithContentImageByteArray : Recommendation2 = {
    title: 'Recommended Movie1',
    text: 'Check out this great movie!',
    contentImageUri: new URL(<content image uri>),
    backgroundImageUri: new URL('https://example.com/background.png'),
    contentUri: new URL('(`orpheus://component-id-of-app-hosting-the-content`'),
    category: Category.HOME,
    displayName: 'Movie App',
    displayActionOption: DisplayAction.WATCH_WITH_APP_DISPLAY_NAME,
    maturityRating: 'PG',
    customerAggregateRating: 8,
    customerRatingCount: 100,
    runningTime: 120,
    releaseYear: 2022,
    isCaptionAvailable: true,
};
const recommendationWithContentImageUri : Recommendation2 = {
    title: 'Recommended Movie2',
    text: 'Check out this great movie!',
    contentImage: [/* image data */],
    backgroundImageUri: new URL('https://example.com/background.png'),
    contentUri: new URL('(`orpheus://component-id-of-app-hosting-the-content`'),
    category: Category.HOME,
    displayName: 'Movie App',
    displayActionOption: DisplayAction.WATCH_WITH_APP_DISPLAY_NAME,
    maturityRating: 'PG',
    customerAggregateRating: 8,
    customerRatingCount: 100,
    runningTime: 120,
    releaseYear: 2022,
    isCaptionAvailable: true,
}

const recommendations: Recommendation2[] = [
    recommendationWithContentImageUri,
    recommendationWithContentImageByteArray
];

try {
    const addedIds = RecommendationManager2.addRecommendations(recommendations);
        console.log('Added recommendations:', addedIds);
    } catch (e) {
        if (e instanceof SecurityError) {
            console.error('Security error:', e.message);
        } else if (e instanceof InvalidArgumentError) {
            console.error('Invalid argument error:', e.message);
        } else {
            console.error('Error adding recommendations:', e);
        }
    }

Removing Recommendations

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

Example:

// Remove a recommendation
RecommendationManager.removeRecommendations([addedIds[0]]);

// Remove all recommendations
RecommendationManager.removeAllRecommendations();

Legacy Use Cases (Version 1.x.x)

Adding legcacy recommendations

Create a Recommendation object with the required fields (title, text, content image, category, display name, display action option, etc.).
Call the addRecommendations() method of the RecommendationManager class, passing an array of Recommendation objects.
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:

import RecommendationManager, { Category, DisplayAction, Recommendation } from './RecommendationManager';

const recommendations: Recommendation[] = [
  {
    title: 'Recommended Movie',
    text: 'Check out this great movie!',
    contentImage: [/* image data */],
    backgroundImageUri: new URL('https://example.com/background.png'),
    contentUri: new URL('(`orpheus://component-id-of-app-hosting-the-content`'),
    category: Category.HOME,
    displayName: 'Movie App',
    displayActionOption: DisplayAction.WATCH_WITH_APP_DISPLAY_NAME,
    maturityRating: 'PG',
    customerAggregateRating: 8,
    customerRatingCount: 100,
    runningTime: 120,
    releaseYear: 2022,
    isCaptionAvailable: true,
  },
];

try {
  const addedIds = RecommendationManager.addRecommendations(recommendations);
  console.log('Added recommendations:', addedIds);
} catch (e) {
  if (e instanceof SecurityError) {
    console.error('Security error:', e.message);
  } else if (e instanceof InvalidArgumentError) {
    console.error('Invalid argument error:', e.message);
  } else {
    console.error('Error adding recommendations:', e);
  }
}

Removing legacy recommendations

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

Sample:

// Remove a recommendation
RecommendationManager.removeRecommendations([addedIds[0]]);

// Remove all recommendations
RecommendationManager.removeAllRecommendations();

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.

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

​Get started

​Permissions

​Setup

​Usage

​Adding Recommendations

​Removing Recommendations

​Legacy Use Cases (Version 1.x.x)

​Adding legcacy recommendations

​Removing legacy recommendations

​The description of recommendation field is as follows

​Acceptable image specification

​Supported maturity rating values

​Troubleshooting

​Modules