文档Analytics流媒体服务指南

在 Roku 中跟踪核心播放 track-core-playback-on-roku

Last update: Tue Jul 15 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • 用户
  • 管理员
  • 开发人员

本文档介绍 2.x 版本的 SDK 中的跟踪。

IMPORTANT
如果您实施的是 1.x 版本的 SDK，可以在此处下载 1.x 开发人员指南：下载 SDK

  1. 初始跟踪设置

    识别用户何时触发播放意图（用户点击“播放”和/或自动播放开启）并创建 MediaObject 实例。

    MediaObject引用：

    table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 3-align-center 7-align-center 11-align-center 15-align-center 19-align-center 23-align-center
    变量名称 描述 必需
    name 视频名称 是
    mediaid 视频唯一标识符 是
    length 视频长度 是
    streamType 流类型（请参阅下面的 StreamType 常量） 是
    mediaType 媒体类型（请参阅下面的 MediaType 常量） 是

    StreamType常量：

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2
    常量名称 描述
    MEDIA_STREAM_TYPE_VOD 点播视频的流类型。
    MEDIA_STREAM_TYPE_LIVE 实时内容的流类型。
    MEDIA_STREAM_TYPE_LINEAR 线性内容的流类型。
    MEDIA_STREAM_TYPE_AOD 点播音频的流类型。
    MEDIA_STREAM_TYPE_AUDIOBOOK 有声读物的流类型。
    MEDIA_STREAM_TYPE_PODCAST 播客的流类型。

    MediaType常量：

    table 0-row-2 1-row-2 2-row-2
    常量名称 描述
    MEDIA_STREAM_TYPE_AUDIO 音频流的媒体类型。
    MEDIA_STREAM_TYPE_VIDEO 视频流的媒体类型。

    为包含 VOD 内容的视频创建媒体信息对象：

    code language-none 
     mediaInfo = adb_media_init_mediainfo(
  "<MEDIA_NAME>",
  "<MEDIA_ID>",
  600,
  ADBMobile().MEDIA_STREAM_TYPE_VOD,
  ADBMobile().MEDIA_TYPE_VIDEO
)

    或

    code language-none 
    mediaInfo = adb_media_init_mediainfo()
mediaInfo.name = "<MEDIA_NAME>"
mediaInfo.id = "<MEDIA_ID>"
mediaInfo.length = 600
mediaInfo.streamType = ADBMobile().MEDIA_STREAM_TYPE_VOD
mediaInfo.mediaType = ADBMobile().MEDIA_TYPE_VIDEO

    为包含 AOD 内容的视频创建媒体信息对象：

    code language-none 
    mediaInfo = adb_media_init_mediainfo(
 "<MEDIA_NAME>",
 "<MEDIA_ID>",
 600,
 ADBMobile().MEDIA_STREAM_TYPE_AOD,
 ADBMobile().MEDIA_TYPE_AUDIO
)

    或

    code language-none 
    mediaInfo = adb_media_init_mediainfo()
mediaInfo.name = "<MEDIA_NAME>"
mediaInfo.id = "<MEDIA_ID>"
mediaInfo.length = 600
mediaInfo.streamType = ADBMobile().MEDIA_STREAM_TYPE_AOD
mediaInfo.mediaType = ADBMobile().MEDIA_TYPE_AUDIO

  2. 附加元数据

    （可选）通过上下文数据变量将标准和/或自定义元数据对象附加到跟踪会话。

    • 标准元数据

在 Roku 中实施标准元数据

 <div class="extension note">
 <div>NOTE</div>
 <div>
 <p>将标准视频元数据对象附加到媒体对象是可选的。</p>
 </div>
 </div>

  • 自定义元数据

    为自定义变量创建变量对象，然后使用此视频的数据进行填充。例如：

    code language-none 
    mediaContextData = {}
mediaContextData["cmk1"] = "cmv1"
mediaContextData["cmk2"] = "cmv2"

  1. 跟踪开始播放的意图

    要开始跟踪媒体会话，请在媒体心率实例中调用 trackSessionStart：

    code language-none 
    ADBMobile().mediaTrackSessionStart(mediaInfo,mediaContextData)
    note tip
    TIP
    第二个值是您在步骤 2 中创建的自定义视频元数据对象名称。
    note important
    IMPORTANT
    trackSessionStart 跟踪的是用户的播放意图，而不是播放的开始。此 API 用于加载视频数据/元数据并评估开启 QoS 量度的时间（trackSessionStart 和 trackPlay 之间的持续时间）。
    note note
    NOTE
    如果不使用自定义视频元数据，则只需在 trackSessionStart 中为 data 参数发送一个空对象，如上面 iOS 示例中注释掉的行所示。

  2. 跟踪播放的实际开始事件

    识别视频播放器中的视频播放开始事件（视频的第一帧呈现在屏幕上）并调用 trackPlay：

    code language-none 
    ADBMobile().mediaTrackPlay()

  3. 更新播放头值

    当媒体播放头发生变化时，通过调用mediaUpdatePlayhead API通知SDK。
    对于视频点播 (VOD)，该值以从媒体项开头开始的秒数指定。
    对于直播，如果播放器不提供有关内容持续时间的信息，则该值可以指定为自当天UTC午夜开始的秒数。

    code language-none 
    ADBMobile().mediaUpdatePlayhead(position)
    note note
    NOTE
    调用mediaUpdatePlayhead API时，请考虑以下事项：
    • 使用进度标记时，需要内容持续时间，并且播放头需要更新为从媒体项目开始的秒数，从0开始。
    • 使用Media SDK时，必须每秒至少调用一次mediaUpdatePlayhead API。

  4. 跟踪播放的结束事件

    识别视频播放器中的视频播放结束事件（用户一直观看至内容的结尾）并调用 trackComplete：

    code language-none 
    ADBMobile().mediaTrackComplete()

  5. 跟踪会话的结束事件

    识别视频播放器中的视频播放卸载/关闭事件（用户关闭视频和/或视频已结束并卸载）并调用 trackSessionEnd：

    code language-none 
    ADBMobile().mediaTrackSessionEnd()
    note important
    IMPORTANT
    trackSessionEnd 标记视频跟踪会话的结尾。如果会话成功观看至结束（用户一直观看内容至结尾），请确保先调用 trackComplete，之后再调用 trackSessionEnd。在调用 trackSessionEnd 之后，任何其他 track* API 调用都将被忽略（除了用于新的视频跟踪会话的 trackSessionStart 之外）。

  6. 跟踪所有可能的暂停方案

    识别视频播放器中的视频暂停事件并调用 trackPause：

    code language-none 
    ADBMobile().mediaTrackPause()

    暂停方案

    识别视频播放器将会暂停的任何方案，并确保正确调用了 trackPause。以下方案均要求应用程序调用 trackPause()：

    • 用户在应用程序中明确点击暂停。
    • 播放器将其置于“暂停”状态。
    • （移动应用程序）- 用户将应用程序放入后台，但您希望应用程序保持会话打开。
    • （移动应用程序）- 发生导致应用程序被置于后台运行的任何类型的系统中断。例如，用户接收到一个调用，或者出现来自其他应用程序的弹出窗口，但您希望应用程序将会话保持活动状态，以便用户有机会从中断点继续观看视频。

  7. 识别播放器中的视频播放事件和/或视频在暂停后继续播放的事件并调用 trackPlay：

    code language-none 
    ADBMobile().mediaTrackPlay()
    note tip
    TIP
    这可能与步骤 4 中所使用的事件源相同。请确保当视频播放继续时，每个 trackPause() API 调用均与随后的一个 trackPlay() API 调用相配对。
recommendation-more-help
c8eee520-cef5-4f8c-a38a-d4952cfae4eb