观看活动
观看活动由内容播放事件组成。该类数据的作用是为客户提供一种简单的方式，从而能更方便地回到他们之前在您的应用中观看的内容。将来我们也可使用这些数据来填写推荐转盘，比如Next Up For You（您可能感兴趣的内容）等。
观看活动可以在本地Fire TV设备上进行，也可以在其他设备上远程进行。对于在同一设备上发生的观看活动，发送播放开始、播放进度、暂停/恢复和播放退出事件。对于远程观看活动，仅发送结束状态（播放退出）事件。这些是更新用户界面时所需要的，例如向用户展示他们正在观看的电视节目的下一剧集，或删除他们已经看过的内容。
要发送的内容
对于每个触发器（参见何时发送），发送一个包含以下字段的事件。无需筛选您发送的数据或检查是否有重复数据。亚马逊会在必要时进行该操作。
| 字段名 | 必填项（是/否） | 描述 |
|---|---|---|
| Event Type（事件类型） | 是 | 该事件可以是Active（有效）或Off-Device（设备外）事件。请参见详情。 |
| Content ID（内容ID） | 是 | 客户当前正在观看的内容的ID，该ID已通过目录集成指定。 |
| Internal Profile ID（内部个人资料ID） | 是 | 提供经过混淆处理的个人资料ID，这样Fire TV就可以将活动与正确的应用客户关联。 |
| Duration（持续时间） | 是 | 内容时间长度（以毫秒为单位）。 |
| Current Playback Position（当前播放位置） | 是 | 与内容开头的偏移量（以毫秒为单位），不包括间隙内容（预览、广告等）。 |
| Credits Position（片尾位置） | 否 | 内容中的片尾位置。与内容开头的偏移量（以毫秒为单位），不包括间隙内容（预览、广告等）。此字段将帮助Fire TV了解客户何时看完内容。 |
| Event Timestamp（事件时间戳） | 否* | *对于设备外事件，此为必填项，但对于有效事件，则并非必填项。 |
| Playback State（播放状态） | 是 | 具有以下可能值的枚举： PLAYING（正在播放）、PAUSED（暂停）、EXIT（退出）或INTERSTITIAL（间隙内容）。 |
事件类型详情
通过addPlaybackEvent函数提供了两种类型的播放事件： Active（有效）和Off-Device（设备外）。
Active（有效）事件在同一台设备上实时主动发生。例如，当客户在其Fire TV上播放您的应用中的某个作品时。只有当前在设备上发生事件时，才将该事件标记为Active（有效）。播放事件上的时间戳字段不用于Active（有效）事件，因为系统会在报告事件时捕获时间戳。
Off-Device（设备外）事件用于在另一台设备上的另一个时间发生的播放。这主要用于捕获最新的客户观看进度，由此Fire TV用户界面可以反映客户在设备上的最新参与数据。Fire TV的设备端服务会定期请求此类数据。此类事件需要时间戳。
如果您在有效播放之外发送播放事件，即使在同一台Fire TV设备上，也要将其标记为Off-Device（设备外），并提供事件发生时间的准确时间戳。不要筛选掉同一设备上的非有效事件。亚马逊将删除重复的有效事件。
何时发送
当以下触发器发生时，发送事件信息：
- 播放状态更改时（开始、停止、暂停或退出）。
- 在寻找新的播放位置时。
- 在播放器中每60秒一次，无论播放状态如何。
- 对于在其他类型的设备上发生的活动：
- Fire TV的设备端服务将定期唤醒并要求您的应用同步此类数据。这将涉及一个参数，该参数指示您应在哪个时间段内共享数据。可以不发送在该时间段内发生的每个播放事件，而是只发送播放退出事件，这将为我们提供内容及其上次观看的进度。
- 在Fire TV设备上处于前台时，您的应用应同步来自您的服务的此类数据，并将最新的观看进度发送给我们。
注意： 有关在亚马逊从您的应用请求设备外数据时如何进行处理的更多信息，请参阅为后台或设备外数据实现数据拉取服务。
发送方式
使用此示例代码发送观看活动事件。
AmazonPlaybackReceiver receiver = AmazonPlaybackReceiver.getInstance(context);
AmazonPlaybackEvent playbackInfo = AmazonPlaybackEvent
.builder()
.playbackPositionMs(0)
.creditsPositionMs(1000)
.state(AmazonPlaybackState.PLAYING)
.durationMs(2000)
.contentId(AmazonContentId.builder()
.id("string")
.namespace(AmazonContentId.NAMESPACE_CDF_ID)
.build())
.profileId(AmazonProfileId.builder()
.id("myProfileId1")
.namespace(AmazonProfileId.NAMESPACE_APP_INTERNAL)
.build())
.buildActiveEvent();
receiver.addPlaybackEvent(playbackInfo);
val receiver: AmazonPlaybackReceiver = AmazonPlaybackReceiver.getInstance(context)
val playbackInfo: AmazonPlaybackEvent = AmazonPlaybackEvent
.builder()
.playbackPositionMs(0)
.creditsPositionMs(1000)
.state(AmazonPlaybackState.PLAYING)
.durationMs(2000)
.contentId(
AmazonContentId.builder()
.id("string")
.namespace(AmazonContentId.NAMESPACE_CDF_ID)
.build()
)
.profileId(
AmazonProfileId.builder()
.id("myProfileId1")
.namespace(AmazonProfileId.NAMESPACE_APP_INTERNAL)
.build()
)
.buildActiveEvent()
receiver.addPlaybackEvent(playbackInfo)
客户体验验证
为何时发送下的每个项目实现SDK调用后，执行以下操作并验证预期结果。
| 验证期望 | 验证步骤 |
|---|---|
| 作品尚未添加到Continue Watching行 | 1. 开始播放未看完的电影作品 2. 立即暂停 3. 导航到Fire TV主页 |
| 作品作为第一个条目出现在主页的Continue Watching行中 | 1. 继续播放电影作品 2. 快进到电影的至少2% 3. 导航到Fire TV主页 |
| 已从Continue Watching行中删除作品 | 1. 开始播放新的电视剧集 2. 立即暂停 3. 导航到Fire TV主页 |
| 电视剧集尚未添加到Continue Watching行 | 1. 开始播放新的电视剧集 2. 立即暂停 3. 导航到Fire TV主页 |
| 具有正确的季和剧集编号的电视剧集将作为Continue Watching行的第一个条目添加 | 1. 恢复电视剧集的播放 2. 允许继续播放，直到您对作品的播放进度至少达到2% 3. 导航到Fire TV主页 |
| 具有正确的季和剧集编号的电视剧剧集仍然是Continue Watching行的第一个作品。 | 1. 继续播放未看完的电视剧集 2. 立即导航到Fire TV主页 |
| 后续剧集的电视连续剧出现在Continue Watching行中 | 1. 继续播放未看完的电视剧集 2. 快进到剧集的结尾 3. 导航到Fire TV主页 |
故障排除
使用本部分可帮助您解决观看活动集成问题。
我的内容均未出现在Continue Watching（继续观看）行中
请参阅一般故障排除： Continue Watching行中不显示任何内容。
某些内容缺失、显示顺序错误或不当删除
以下是可能会影响您的集成的常见问题。
- 亚马逊内容ID不正确
- 确认您在SDK集成中使用的亚马逊内容ID与您在目录中使用的ID完全匹配至关重要。SDK日志不包含内容ID。因此，在开发过程中，可以考虑在您的应用中添加包含ID的调试日志。使用此日志来验证您是否在发送预期的内容ID。有关目录集成的详细信息，请参阅EMBER目录集成概述。
- 不正确地报告播放事件
- 每个播放事件都必须准确地表示状态。Continue Watching（继续观看）行的构造依赖于应用报告的准确数据。下表描述了应避免的行为。
勿做事项 应做事项 在播放器加载用户的实际播放位置之前，发送当前位置= 0的播放事件 加载播放器后，发送包含客户正确位置的播放事件 在播放间隙内容（广告、简介、预览等）时向前移动当前播放位置 发送包含内容的当前播放位置的间隙内容播放事件 播放内容时不会定期报告更新的播放位置 播放内容时每60秒发送一次播放事件 退出内容时发送PAUSE（暂停）事件 播放完成后发送EXIT（退出）播放事件 有关何时发送事件的更多详细信息，请查看何时发送。
- 设备外活动未更新Continue Watching行
- Fire TV服务目前未使用设备外活动来影响Continue Watching行。
- 来自多个应用内个人资料的内容出现在我的Continue Watching行中
- Continue Watching行基于从当前有效的Fire TV个人资料中记录的播放事件，如果用户在您的应用中更改了个人资料但继续使用相同的Fire TV个人资料，则这些事件也将包含在该个人资料中。这是预期的行为。
Last updated: 2026年5月27日
