Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

观看活动

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发行说明。

观看活动数据由内容播放事件组成。该类数据的作用是为客户提供一种简单的方式，方便回到他们之前在您的应用中观看的内容。将来我们也可使用这些数据来填充推荐转盘，比如Next Up For You（您可能感兴趣的内容）。

观看活动可以在本地Fire TV设备上进行，也可以在其他设备上远程进行。对于在同一设备上发生的观看活动，发送播放开始、播放进度、暂停/恢复和播放退出事件。对于远程观看活动，仅发送结束状态（播放退出）事件。这些事件是更新用户界面时所需要的，例如向客户展示其正在观看的电视节目的下一集，或是删除他们已经看过的内容。

要发送的内容

对于每个触发器（参见“何时发送”），发送包含以下字段的事件。无需筛选您发送的数据或检查是否有重复数据。亚马逊会在必要时进行该操作。

字段名	必填项（是/否）	描述
Content ID（内容ID）	是	客户正在观看的通过亚马逊目录集成指定内容的ID。
Live Channel Descriptor（直播频道描述符）	是*	正在播放通过目录集成指定内容的直播线性频道的频道描述符。 *仅对直播内容为必填项。
Internal Profile ID（内部个人资料ID）	是	提供经过混淆处理的个人资料ID，以便Fire TV将活动与正确的应用客户关联。
Duration（持续时间）	是	内容时间长度（以毫秒为单位）。
Current Playback Position（当前播放位置）	是	与内容开头的偏移量（以毫秒为单位），不包括间隙内容（预览、广告等）。
Credits Position（片尾位置）	否	内容中的片尾位置。与内容开头的偏移量（以毫秒为单位），不包括间隙内容（预览、广告等）。此字段将帮助Fire TV了解客户何时看完内容。
Event Timestamp（事件时间戳）	否*	* 对于设备外事件，此项为必填项；但对于有效事件，则并非必填项。
Playback State（播放状态）	是	表示内容播放状态的枚举。请参阅API文档。

事件类型详情

提供了两种类型的播放事件：addPlaybackEvent function: Active和Off-Device。

Active（有效）事件在同一台设备上实时发生。例如，当客户在其Fire TV上播放您的应用中的某个作品时。只有当前在设备上发生事件时，才将该事件标记为Active。播放事件上的时间戳字段不用于有效事件，因为系统会在报告事件时捕获时间戳。

Off-Device（设备外）事件用于在另一个时间、另一台设备上发生的播放。这主要用于捕获最新的客户观看进度，以便Fire TV用户界面反映客户在不同设备上的最新互动数据。Fire TV的设备端服务会定期请求此类数据。此类事件需要时间戳。

如果您在有效播放之外发送播放事件，即使在同一台Fire TV设备上，也要将其标记为Off-Device，并提供事件发生时的精确时间戳。不要筛选掉同一设备上的非有效事件。亚马逊将删除重复的有效事件。

何时发送

当以下触发器发生时，发送事件信息：

播放状态更改时：开始、停止、暂停或退出。
寻找新的播放位置时。
在播放器中每60秒发生一次，无论播放状态如何。
对于在其他类型的设备上发生的活动：
- Fire TV的设备端服务将定期唤醒并要求您的应用同步此类数据。这涉及一个参数，该参数会指示应共享数据的时间段。可以不发送在该时间段内发生的每个播放事件，而是发送播放退出事件，为我们提供相关内容及其上次观看的进度。
- 在Fire TV设备上处于前台时。让您的应用同步来自您的服务的此类数据，并将最新观看进度发送给我们。
注意： 有关如何处理亚马逊向您的应用请求设备外数据这一情况的更多信息，请参阅步骤6：实现面向后台或设备外数据的数据拉取服务。

发送方式

在用户与您的应用交互时，使用以下示例代码发送观看活动事件：

已复制到剪贴板。

// 用户开始观看直播内容时生成的示例播放事件

const playbackEvent: IPlaybackEvent = new PlaybackEventBuilder()
   .playbackPositionMs(0)
   .playbackState(PlaybackState.PLAYING)
   .durationMs(2000)
   .eventTimestamp(new Date())
   .contentId(
   new ContentIdBuilder()
      .id('content_CDF_ID')
      .idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
      .build(),
   )
   .channelDescriptor(new ChannelDescriptorBuilder()
      .majorNumber(0)
      .minorNumber(1)
      .identifier('channelID')
      .build(),
   )
   .profileId(
   new ProfileIdBuilder()
      .id('myProfileId')
      .idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
      .build(),
   )
   .buildActiveEvent();

// 发送事件
ContentPersonalizationServer.reportNewPlaybackEvent(playbackEvent);

通过内容个性化数据服务引用您的应用时，使用以下示例TypeScript代码发送设备外观看活动数据：

已复制到剪贴板。

const playbackEventsHandler: IPlaybackEventsHandler = {
    getPlaybackEventsSince: (
      sinceTimestamp: Date,
      playbackEventsProvider: IPlaybackEventsProvider,
    ) => {
        let playbackEvents: IPlaybackEvent[] = [];
        
        const playbackEvent: IPlaybackEvent = new PlaybackEventBuilder()
            .playbackPositionMs(0)
            .creditsPositionMs(1000)
            .playbackState(PlaybackState.EXIT)
            .durationMs(2000)
            .eventTimestamp(new Date())
            .contentId(new ContentIdBuilder()
                .id('content_CDF_ID')
                .idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
                .build(),
             )
            .profileId(new ProfileIdBuilder()
                .id('myProfileId')
                .idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
                .build(),
            )
            .buildOffDeviceEvent();
            
        playbackEvents.add(playbackEvent);
        
        playbackEventsProvider.addPlaybackEventChunk(playbackEvents);
        playbackEventsProvider.commit();
    }
};

// 务必要在HeadlessService的onStart函数中设置播放事件处理程序
ContentPersonalizationServer.setPlaybackEventsHandler(
        playbackEventsHandler,
);

客户体验验证

为何时发送下的每个项目实现SDK调用后，执行以下操作并验证结果。

设置您的设备

设置并注册您的Fire TV设备。
应用内容应与Fire TV进行目录集成。
将启用Vega内容个性化功能的应用安装到设备上，然后启动该应用。
您必须为此账户同意Continue Watching功能。为此，请按照以下说明操作：
1. 前往Settings（设置）> Preferences（首选项）> Privacy Settings（隐私设置）> Manage Sharing from Apps（管理来自应用的共享内容）> Share App Viewing and Content Info（共享应用查看权限和内容信息）> Turn On（开启）
2. 前往Settings > Preferences > Privacy Settings > Manage Sharing from Apps > Sync Across Devices（跨设备同步）> Turn On

验证Continue Watching行中的内容更新

在视频播放期间，您的应用必须定期报告观看活动事件。用户开始观看内容后，系统会将该内容添加到Continue Watching（继续观看）行。

在您的应用中，打开视频并播放。观看或滚动浏览视频，至少达到2%的进度。
单击停止或返回钮停止视频播放。

检查日志以验证是否已成功报告播放事件。如果成功报告，您将看到以下日志行。

INFO com.amazon.com_amazon_tv_developer_dataservice.vega.vega_alberto_service:VegaAlbertoBinderService PlaybackEventsVegaMessage → message.sent_timestamp: <时间戳>, page_index : 0, total_page_count: 1, content_id id : <内容ID>, content_id namespace : cdf_id, event_timestamp_ms: <时间戳>, playback_state :0, duration_ms : <内容时间长度>, credits_position_ms :<内容片尾位置>

使用遥控器，或通过退出应用或单击主页按钮，返回主屏幕。
您应该会看到更新后的Continue Watching行。您观看的视频应该正在播放。如果是，则表示工作正常。
如果Continue Watching行未更新，请从Home选项卡导航到任何其他选项卡，然后再次返回Home选项卡。
您还可以执行以下操作，从Continue Watching行中移除图块：
1. 将鼠标悬停在图块上 > 单击遥控器上的菜单按钮 > 从Continue Watching中选择Remove（移除）。您可以通过这种方式，对相同的内容进行测试。

验证内容是否已从Continue Watching行中移除

在视频播放期间，您的应用必须定期报告观看活动事件，并在播放完成或中断时进行报告。如果当前播放位置接近总时间长度，则表示用户已完成视频的观看，系统将从Continue Watching行中移除该内容。

打开您的应用，开始观看已在Continue Watching行中列出的内容的视频。
通过搜索视频的末尾或反复单击遥控器上的快进 (») 滚动按钮来转到视频的末尾。

检查日志以验证是否成功报告了播放停止事件。如果成功报告，您的日志将具有与以下所示类似的内容。

INFO com.amazon.com_amazon_tv_developer_dataservice.vega.vega_alberto_service:VegaAlbertoBinderService PlaybackEventsVegaMessage → message.sent_timestamp:  <时间戳> , page_index : 0, total_page_count: 1, content_id id : <内容ID>, content_id namespace : cdf_id, event_timestamp_ms: <时间戳>, playback_state :2, duration_ms : <内容时间长度>, credits_position_ms : <内容片尾位置>

返回Home选项卡。
Continue Watching行不应再显示内容。
如果Continue Watching行未更新，请从Home选项卡导航到任何其他选项卡，然后返回到Home选项卡以触发用户界面刷新。

验证场景

按照下面相关步骤在Continue Watching行中添加或移除图块。验证每个场景。

验证期望	验证步骤
作品尚未添加到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主页

故障排除

以下列出了您在集成过程中可能会遇到的一些常见问题：

CDF ID不正确

SDK中使用的目录数据格式 (CDF) ID必须与您的目录引入中使用的ID完全匹配。日志将不包含任何CDF ID，因此我们建议在开发过程中在应用中添加包含该ID的调试日志，以验证您是否发送了预期的CDF ID。请参阅目录引入入门。

不正确地报告播放事件

每个播放事件都必须准确地表示状态。Continue Watching行的构造依赖于应用报告的准确数据。以下列出了一些需要避免的行为，以及一些应做事项：

勿做事项	应做事项
在播放器加载用户的实际播放位置之前，发送包含当前位置的播放事件。	加载播放器后，发送包含客户正确位置的播放事件。
在播放间隙内容（广告、简介、预览等）时向前移动当前播放位置	发送间隙内容播放事件，其中包含内容的当前播放位置。
播放内容时定期报告更新的播放位置。	播放内容时每60秒发送一次播放事件。
退出内容时发送PAUSE（暂停）事件。	播放完成后发送EXIT（退出）播放事件。

有关何时发送事件的更多详细信息，请查看何时发送。

设备外活动未更新Continue Watching行

这是预期的行为。Fire TV服务不会使用设备外活动来影响Continue Watching行。

来自多个应用内个人资料的内容出现在Continue Watching行中

Continue Watching行基于从当前处于活跃状态的Fire TV个人资料记录的播放事件。如果用户在您的应用中更改了个人资料，但在Fire TV中继续使用原来的个人资料，则这些事件也将包含在该个人资料中。这是预期的行为。

Last updated: 2025年9月30日