跟踪概述 tracking-overview

Last update: Fri Jul 21 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：
Media Analytics

创建对象：

User
Admin
Developer

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

IMPORTANT

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

播放器事件

跟踪核心播放包括跟踪媒体载入、媒体开始、媒体暂停和媒体结束。虽然跟踪缓冲和搜索不是强制的，但它们也是用于跟踪内容播放的核心组件。在您的媒体播放器 API 中，识别与 Media SDK 跟踪调用相对应的播放器事件，并编码事件处理程序以调用跟踪 API，并填充必需和可选变量。

在媒体载入时

创建媒体对象
填充元数据
调用 trackSessionStart；例如：trackSessionStart(mediaObject, contextData)

在媒体开始时

调用 trackPlay

在暂停/继续播放时

调用 trackPause
在继续播放时，调用 trackPlay

在媒体结束时

调用 trackComplete

在媒体中止时

调用 trackSessionEnd

在推移开始时

调用 trackEvent(SeekStart)

在推移结束时

调用 trackEvent(SeekComplete)
取消更改

在缓冲开始时

调用 trackEvent(BufferStart);

在缓冲结束时

调用 trackEvent(BufferComplete);

实施 implement

初始跟踪设置 – 识别用户何时触发播放意图（用户点击“播放”和/或自动播放开启），并使用媒体的内容名称、内容 ID、内容时长和流类型信息，创建 MediaObject 实例。

MediaObject引用：

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3
变量名称	描述	必需
`name`	内容名称	是
`mediaid`	内容唯一标识符	是
`length`	内容时长	是
`streamType`	流类型	是
`mediaType`	媒体类型（音频或视频内容）	是

StreamType常量：

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2
常量名称	描述
`VOD`	点播视频的流类型。
`LIVE`	实时内容的流类型。
`LINEAR`	线性内容的流类型。
`AOD`	点播音频的流类型。
`AUDIOBOOK`	有声读物的流类型。
`PODCAST`	播客的流类型。

MediaType常量：

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

创建 MediaObject 的一般格式是 MediaHeartbeat.createMediaObject(<MEDIA_NAME>, <MEDIA_ID>, <MEDIA_LENGTH>, <STREAM_TYPE>, <MEDIA_TYPE>);

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

标准元数据 -

note note
NOTE
将标准元数据对象附加到媒体对象是可选的。

实例化一个标准元数据对象，填充所需变量，并在媒体心跳对象中设置该元数据对象。

请在此处查看元数据的完整列表：音频和视频参数。

自定义元数据 - 为自定义变量创建变量对象，然后使用此内容的数据进行填充。

跟踪开始播放的意图 - 要开始跟踪会话，请在 MediaHeartbeat 实例中调用 trackSessionStart。

note important
IMPORTANT
`trackSessionStart` 跟踪的是用户的播放意图，而不是播放的开始。此 API 用于加载数据/元数据并评估开启 QoS 量度的时间（`trackSessionStart` 和 `trackPlay` 之间的持续时间）。

note note
NOTE
如果不使用自定义元数据，则只需在 `trackSessionStart` 中为 `data` 参数发送一个空对象。

跟踪播放的实际开始事件 - 识别媒体播放器中的播放开始事件（内容的第一帧呈现在屏幕上）并调用 trackPlay。
跟踪播放的结束事件 - 识别媒体播放器中的播放结束事件（用户一直观看至内容的结尾）并调用 trackComplete。

跟踪会话的结束事件 - 识别媒体播放器中的播放卸载/关闭事件（用户关闭内容和/或内容已结束并卸载）并调用 trackSessionEnd。

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

跟踪所有可能的暂停方案 - 识别媒体播放器中的暂停事件并调用 trackPause。

暂停方案 - 识别播放器将会暂停的任何方案，并确保正确调用了 trackPause。以下方案均要求应用程序调用 trackPause()：
- 用户在应用程序中明确点击暂停。
- 播放器将其置于“暂停”状态。
- （移动应用程序）- 用户将应用程序放入后台，但您希望应用程序保持会话打开。
- （移动应用程序）- 发生导致应用程序被置于后台运行的任何类型的系统中断。例如，用户接到电话，或其他应用程序出现弹出窗口，但您希望应用程序保持会话的活动状态，以便用户有机会从中断点恢复内容。

识别播放器中的播放事件和/或在暂停后继续播放的事件并调用 trackPlay。

note tip
TIP
这可能与步骤 4 中所使用的事件源相同。请确保当播放继续时，每个 `trackPause()` API 调用均与随后的一个 `trackPlay()` API 调用相配对。

监听媒体播放器中的播放搜寻事件。在发出搜寻开始事件通知时，使用 SeekStart 事件跟踪搜寻。
在从媒体播放器发出搜寻结束通知时，使用 SeekComplete 事件跟踪搜寻的结束。
监听媒体播放器中的播放缓冲事件，并在发出缓冲开始事件通知时，使用 BufferStart 事件跟踪缓冲。
在从媒体播放器发出缓冲结束通知时，使用 BufferComplete 事件跟踪缓冲的结束。

查看以下平台特定主题中每个步骤的示例，并查看 SDK 附带的示例播放器。

有关播放跟踪的简单示例，请参阅在 HTML5 播放器中对 JavaScript 2.x SDK 的使用：

/* Call on media start */
if (e.type == "play") {

    // Check for start of media
    if (!sessionStarted) {
        /* Set media info */
        /* MediaHeartbeat.createMediaObject(<MEDIA_NAME>,
                                            <MEDIA_ID>,
                                            <MEDIA_LENGTH>,
                                            <MEDIA_STREAMTYPE>,
                                            <MEDIA_MEDIATYPE>);*/
        var mediaInfo = MediaHeartbeat.createMediaObject(
          document.getElementsByTagName('video')[0].getAttribute("name"),
          document.getElementsByTagName('video')[0].getAttribute("id"),
          video.duration,
          MediaHeartbeat.StreamType.VOD);

        /* Set custom context data */
        var customVideoMetadata = {
            isUserLoggedIn: "false",
            tvStation: "Sample TV station",
            programmer: "Sample programmer"
        };

        /* Set standard video metadata */
        var standardVideoMetadata = {};
        standardVideoMetadata[MediaHeartbeat.VideoMetadataKeys.EPISODE] = "Sample Episode";
        standardVideoMetadata[MediaHeartbeat.VideoMetadataKeys.SHOW] = "Sample Show";
        mediaInfo.setValue(MediaHeartbeat.MediaObjectKey.StandardVideoMetadata,
                           standardVideoMetadata);

        // Start Session
        this.mediaHeartbeat.trackSessionStart(mediaInfo, customVideoMetadata);

        // Track play
        this.mediaHeartbeat.trackPlay();
        sessionStarted = true;

    } else {
        // Track play for resuming playack
        this.mediaHeartbeat.trackPlay();
    }
};

/* Call on video complete */
if (e.type == "ended") {
    console.log("video ended");
    this.mediaHeartbeat.trackComplete();
    this.mediaHeartbeat.trackSessionEnd();
    sessionStarted = false;
};

/* Call on pause */
if (e.type == "pause") {
    this.mediaHeartbeat.trackPause();
};

/* Call on scrub start */
if (e.type == "seeking") {
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.SeekStart);
};

/* Call on scrub stop */
if (e.type == "seeked") {
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.SeekComplete);
};

/* Call on buffer start */
if (e.type == "buffering") {
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.BufferStart);
};

/* Call on buffer complete */
if (e.type == "buffered") {
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.BufferComplete);
};

验证 validate

有关验证旧版实施的信息，请参阅旧版验证。

recommendation-more-help

c8eee520-cef5-4f8c-a38a-d4952cfae4eb