观看活动

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

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

要发送的内容
- 事件类型详情
何时发送
发送方式
- 我的内容均未出现在Continue Watching行中
- 某些内容缺失、显示顺序错误或不当删除
客户体验验证
故障排除
- 我的内容均未出现在Continue Watching行中
- 某些内容缺失、显示顺序错误或不当删除

要发送的内容

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

字段名	必填项（是/否）	描述
Event Type（事件类型）	是	该事件可以是Active（有效）或Off-Device（设备外）事件。请参见详情。
Content ID（内容ID）	是	通过目录集成指定的客户正在观看的内容的ID。
Live Channel Station ID（直播频道电视台ID）	是*	通过目录集成播放指定内容的直播线性频道的ID。 *仅对直播内容为必填项。
Internal Profile ID（内部个人资料ID）	是	提供经过混淆处理的Profile 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 UI可以反映客户在设备上的最新参与数据。Fire TV的设备端服务会定期请求此类数据。此类事件需要时间戳。

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

何时发送

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

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

发送方式

使用此示例代码发送观看活动事件：

Java
Kotlin

 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)

我的内容均未出现在Continue Watching行中

请参阅一般故障排除： Continue Watching行中不显示任何内容。

某些内容缺失、显示顺序错误或不当删除

以下是一些可能导致集成出现问题的常见陷阱：

CDF ID不正确: 务必要确保SDK中使用的目录数据格式 (CDF) ID与您的目录引入中使用的ID完全匹配。SDK日志将不包括CDF ID，因此我们建议在开发过程中在应用中添加包含该ID的调试日志，以验证您是否发送了预期的CDF ID。请参阅目录引入入门。
不正确地报告播放事件: 每个播放事件都必须准确地表示状态。Continue Watching行的构造依赖于应用报告的准确数据。以下是一些您务必要避免的行为：

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

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

设备外活动未更新Continue Watching行: Fire TV服务目前未使用设备外活动来影响Continue Watching行。
来自多个应用内个人资料的内容出现在我的Continue Watching行中: Continue Watching行基于从当前有效的Fire TV个人资料中记录的播放事件，如果用户在您的应用中更改了个人资料但继续使用相同的Fire TV个人资料，则这些事件也将包含在该个人资料中。这是预期的行为。

客户体验验证

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

注意： 如果您没有看到内容立即显示在Continue Watching（继续观看）行中，则可能需要等待达5分钟才能刷新该行。您可以前往Settings（设置）> Account & Profile Settings（账户和个人资料设置）> Sync Amazon Content（同步亚马逊内容）来强制行刷新。

验证期望	验证步骤
作品尚未添加到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行中不显示任何内容。

某些内容缺失、显示顺序错误或不当删除

以下是一些可能导致集成出现问题的常见陷阱：

CDF ID不正确: 务必要确保SDK中使用的目录数据格式 (CDF) ID与您的目录引入中使用的ID完全匹配。SDK日志将不包括CDF ID，因此我们建议在开发过程中在应用中添加包含该ID的调试日志，以验证您是否发送了预期的CDF ID。请参阅目录引入入门。
不正确地报告播放事件: 每个播放事件都必须准确地表示状态。Continue Watching行的构造依赖于应用报告的准确数据。以下是一些您务必要避免的行为：

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

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

设备外活动未更新Continue Watching行: Fire TV服务目前未使用设备外活动来影响Continue Watching行。
来自多个应用内个人资料的内容出现在我的Continue Watching行中: Continue Watching行基于从当前有效的Fire TV个人资料中记录的播放事件，如果用户在您的应用中更改了个人资料但继续使用相同的Fire TV个人资料，则这些事件也将包含在该个人资料中。这是预期的行为。

现在让我们来了解另一种数据类型：个人内容权利。

Last updated: 2024年3月1日