Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
Ring
AWS
文档
Support
Contact Us
My Cases

Console

as

新手入门
设计和开发
应用发布
参考
支持

@amazon-devices/recommendation-manager

@amazon-devices/recommendation-manager

亚马逊媒体推荐API是一项服务，允许客户端应用在亚马逊设备上添加和删除推荐内容。API将这些推荐内容显示在设备的主屏幕上，为用户提供个性化的内容推荐。该API旨在根据用户的偏好和观看历史，提供相关且引人入胜的推荐内容，由此增强用户体验。

API包含两个实现：

  • RecommendationManager
  • RecommendationManager2

从API的2.x.x版本开始，新应用应使用RecommendationManager2实现来发送推荐。该实现通过内容图像字节数组和内容图像URI支持内容图像。我们鼓励您将旧应用更新到RecommendationManager2以使用其增强功能。

开始使用

权限

API需要通过使用权限进行身份验证。具体而言，应用需要具有com.amazon.privilege.security.file-sharing权限才能访问用于添加推荐项目的API。

设置

  1. 将以下库依赖项添加到package.json文件的dependencies部分。

    已复制到剪贴板。

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

  2. 在您的manifest.toml中，添加以下权限。

    已复制到剪贴板。

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

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

用法

添加推荐

  1. 使用必填字段（标题、文本、内容图像、类别、显示名称、显示操作选项等）创建Recommendation2对象。
  2. 调用RecommendationManager2类的addRecommendations2方法，传递一个Recommendation2对象数组。
  3. 该方法返回代表新添加推荐项目的数字数组。每个数字对应一个推荐，并可用于在将来删除推荐：
    • 如果您指定内容图像字节数组，则图像将立即存储在设备上。
    • 如果您指定内容图像URI，则将异步下载图像。如果图像下载失败，则会删除推荐并记录一条错误消息，表明内容图像URI下载失败。

注意：​ 如果您同时指定内容图像字节数组和内容图像URI，则RecommendationManager2默认为内容图像字节数组。

注意：​ React Native URL构造函数会自动向URL添加尾随的/。这可能会导致内容图像URI下载失败。要解决此问题，请执行以下操作：

  1. 使用标准URL构造器创建URL
  2. 手动将_url字段设置为所需的确切URL字符串

已复制到剪贴板。

  const imageUrl = new URL('https://example.com/image.png');
  (imageUrl as any)._url = 'https://example.com/image.png';  // 移除尾部的斜杠

  // 在Recommendation2对象中
  contentImageUri: imageUrl

此问题将在推荐管理器的未来版本中得到解决。请注意，替代URL解析库（例如react-native-url-polyfill）不兼容，因为推荐管理器需要标准URL对象中的特定字段。

示例：

已复制到剪贴板。

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

const recommendationWithContentImageByteArray : Recommendation2 = {
    title: '推荐电影1',
    text: '看看这部很棒的电影！',
    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: '电影应用',
    displayActionOption: DisplayAction.WATCH_WITH_APP_DISPLAY_NAME,
    maturityRating: 'PG',
    customerAggregateRating: 8,
    customerRatingCount: 100,
    runningTime: 120,
    releaseYear: 2022,
    isCaptionAvailable: true,
};
const recommendationWithContentImageUri : Recommendation2 = {
    title: '推荐电影2',
    text: '看看这部很棒的电影！',
    contentImage: [/* 图像数据 */],
    backgroundImageUri: new URL('https://example.com/background.png'),
    contentUri: new URL('(`orpheus://component-id-of-app-hosting-the-content`'),
    category: Category.HOME,
    displayName: '电影应用',
    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('添加了推荐：', addedIds);
    } catch (e) {
        if (e instanceof SecurityError) {
            console.error('安全错误：', e.message);
        } else if (e instanceof InvalidArgumentError) {
            console.error('无效参数错误：', e.message);
        } else {
            console.error('添加推荐时出错：', e);
        }
    }

删除推荐

  1. 要删除特定推荐，请调用RecommendationManager2类的removeRecommendations() 方法，传递代表要删除的推荐项目的数字数组。
  2. 要删除客户端应用发送的所有推荐，请调用RecommendationManager2类的removeAllRecommendations() 方法。

示例：

已复制到剪贴板。

// 删除推荐
RecommendationManager.removeRecommendations([addedIds[0]]);

// 删除所有推荐
RecommendationManager.removeAllRecommendations();

传统用例（版本1.x.x）

添加旧版推荐

  1. 使用必填字段（标题、文本、内容图像、类别、显示名称、显示操作选项等）创建Recommendation对象。
  2. 调用RecommendationManager类的addRecommendations() 方法，传递Recommendation对象数组。
  3. 该方法返回代表新添加推荐项目的数字数组。每个数字对应一个推荐，并可用于在将来删除推荐。

示例

已复制到剪贴板。

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

const recommendations: Recommendation[] = [
  {
    title: '推荐电影',
    text: '看看这部很棒的电影！',
    contentImage: [/* 图像数据 */],
    backgroundImageUri: new URL('https://example.com/background.png'),
    contentUri: new URL('(`orpheus://component-id-of-app-hosting-the-content`'),
    category: Category.HOME,
    displayName: '电影应用',
    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('添加了推荐：', addedIds);
} catch (e) {
  if (e instanceof SecurityError) {
    console.error('安全错误：', e.message);
  } else if (e instanceof InvalidArgumentError) {
    console.error('无效参数错误：', e.message);
  } else {
    console.error('添加推荐时出错：', e);
  }
}

移除旧版推荐

  1. 要删除特定推荐，请调用RecommendationManager类的removeRecommendations() 方法，传递代表要删除的推荐项目的数字数组。
  2. 要删除客户端应用发送的所有推荐，请调用RecommendationManager类的removeAllRecommendations() 方法。

示例

已复制到剪贴板。

// 删除推荐
RecommendationManager.removeRecommendations([addedIds[0]]);

// 删除所有推荐
RecommendationManager.removeAllRecommendations();

推荐字段的描述如下

字段 类型 描述 是否必需
title string 推荐项目的内容标题。 否
text string 推荐项目的描述文本。 否
contentImage number[] 为此推荐显示的图像 (PNG)。图像规格不正确的推荐在调用addRecommendations() 方法时会返回InvalidArgumentError。有关可接受的图像格式的详细信息，请参阅可接受的图像规格。 是
contentImageUri URL 用于检索要根据此推荐显示的图像 (PNG) 的URI。图像规格不正确的推荐在调用addRecommendations() 方法时会返回InvalidArgumentError。有关可接受的图像格式的详细信息，请参阅可接受的图像规格。 是
backgroundImageUri URL 用于检索推荐项目的背景图像的URI。当用户将鼠标悬停在推荐项目上方时，会显示该图像。 否
contentUri URL 用户点击推荐时启动的URI。 否
category Category 推荐应归入的类别（例如，主页、您的视频、直播、超高清）。 是
displayName string Launch（启动）菜单中显示的较短应用名称（在选择推荐时按菜单按钮会显示该名称）。 否
displayActionOption DisplayAction 确定为每个推荐显示的第一上下文菜单选项。 是
maturityRating string 在标题下方显示年龄评级。有关可接受的年龄评级的详细信息，请参阅支持的年龄评级值。 是
customerAggregateRating number 汇总所有客户的评分，可能的值介于0到10之间。 否
customerRatingCount number 对此内容进行评分的客户数量。如果设置为0，则将内容视为未评分。 否
runningTime number 如果适用，则为内容的运行时间（以分钟为单位）。直播内容可以将此项设置为0。 否
releaseYear number 内容的发布年份。示例： 2016、2015。 否
isCaptionAvailable boolean 表示有字幕可用于内容 (true) 或表示没有字幕 (false)。false表示没有字幕可用于内容（默认）。true表示内容有字幕。 否

可接受的图像规格

  • 宽高比： 16:9
  • 频道： 3 (BGR)，8位/频道
  • 方向： 横向
  • 格式： PNG
  • 根据显示器的不同，图像分辨率应为：
    • HDTV (720p)： 256 * 144
    • HDTV (1080p)： 384 * 216
    • 4K超高清： 768 * 432
  • 标题： 嵌入在图像中
  • 透明度： 不透明

支持的年龄评级值

  • 美国市场： G、PG、PG13、R、NC17、NR、TVY、TVY7、TVG、TVPG、TV14、TVMA
  • 德国市场： FSK0、FSK6、FSK12、FSK16、FSK18
  • 英国市场： BBFCPG、BBFC12、BBFC18、BBFCU
  • 日本市场： EIRIN_G、EIRIN_PG12、EIRIN_R15、EIRIN_18
  • 印度市场： ALL、7+、13+、16+、18+、NR

故障排除

  • SecurityError： 当调用应用没有所需的com.amazon.privilege.security.file-sharing权限时，就会出现此错误。在调用API之前，请确保您的应用具有必要的权限。
  • InvalidArgumentError： 此错误可能发生在以下场景中：
    • 推荐对象的大小超过512KB（不包括内容图像大小）。
    • Recommendation对象中的必填字段为空或无效。
    • 内容图像不符合指定的尺寸和大小要求。
    • 传递给addRecommendations() 的推荐数组的大小大于20。

  • 在未显示推荐的情况下：

    • 如果您使用了该内容图像URI，请检查图像是否下载失败。如果图像下载失败，则不添加推荐。设备日志将显示图像下载失败。例如：

      Failed to fetch image for recommendation.Ignoring it.

    • 使用唯一行ID检查推荐是否已成功添加到推荐管理器数据库中。唯一行ID可以在日志中找到：

      recommendation_[4509]: 8 I recommendationCommonLib:[log_impl.cpp:14] Recommendations are for config: <唯一行ID>

      找到unique-row-id后，检查与唯一行ID对应的配置文件。该文件包含已成功添加到该行的推荐。如果该文件为空，则表示未添加调用应用的推荐。在调用addRecommendations时，检查设备日志中是否有错误日志。

      已复制到剪贴板。

      adb shell cat /home/app_user_packages/com.amazon.recommendation.service/data/<唯一行ID>

模块

Last updated: 2026年6月30日

关注我们:
amazon_developer_logo

© 2010-2026 年，亚马逊公司或其附属公司. 保留所有权利。

协议

开发人员博客

联系我们