在 iOS 中跟踪核心播放

重要

本文档介绍 2.x 版本的 SDK 中的跟踪。如果您实施的是 1.x 版本的 SDK，可以在此处下载 1.x 开发人员指南：下载 SDK

初始跟踪设置

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

变量名称	描述	必需
`name`	视频名称	是
`mediaid`	视频唯一标识符	是
`length`	视频长度	是
`streamType`	流类型（请参阅下面的 StreamType 常量）	是
`mediaType`	媒体类型（请参阅下面的 MediaType 常量）	是

StreamType常量：

常量名称	描述
`ADBMediaHeartbeatStreamTypeVOD`	点播视频的流类型。
`ADBMediaHeartbeatStreamTypeLIVE`	实时内容的流类型。
`ADBMediaHeartbeatStreamTypeLINEAR`	线性内容的流类型。
`ADBMediaHeartbeatStreamTypeAOD`	点播音频的流类型。
`ADBMediaHeartbeatStreamTypeAUDIOBOOK`	有声读物的流类型。
`ADBMediaHeartbeatStreamTypePODCAST`	播客的流类型。

MediaType常量：

常量名称	描述
`ADBMediaTypeAudio`	音频流的媒体类型。
`ADBMediaTypeVideo`	视频流的媒体类型。

创建 MediaObject 的一般格式：

ADBMediaObject *mediaObject =  
  [ADBMediaHeartbeat createMediaObjectWithName:<MEDIA_NAME> 
                                       mediaId:<MEDIA_ID> 
                                        length:<MEDIA_LENGTH>                       
                                    streamType:<STREAM_TYPE> 
                                     mediaType: <MEDIA_TYPE>];

附加视频元数据

（可选）通过上下文数据变量将标准和/或自定义视频元数据对象附加到视频跟踪会话。
- 标准视频元数据
  - 在 iOS 中实施标准元数据
  - 视频元数据键
    iOS 元数据键
  - 请在此处查看视频元数据的完整列表：音频和视频参数
  注意
  
  将标准视频元数据对象附加到媒体对象是可选的。
- 自定义元数据
  
  为自定义变量创建变量对象，然后使用此视频的数据进行填充。例如：
```
NSMutableDictionary *videoMetadata = [[NSMutableDictionary alloc] init]; 
[videoMetadata setObject:@"false" forKey:@"isUserLoggedIn"]; 
[videoMetadata setObject:@"Sample TV station" forKey:@"tvStation"];
```
跟踪开始播放的意图

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

小贴士

第二个值是您在步骤 2 中创建的自定义视频元数据对象名称。
```
- (void)onMainVideoLoaded:(NSNotification *)notification { 
//    [_mediaHeartbeat trackSessionStart:mediaObject data:nil]; 
    [_mediaHeartbeat trackSessionStart:mediaObject data:videoMetadata]; 
}
```
重要

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

注意

如果不使用自定义视频元数据，则只需在 trackSessionStart 中为 data 参数发送一个空对象，如上面 iOS 示例中注释掉的行所示。
跟踪播放的实际开始事件

识别视频播放器中的视频播放开始事件（视频的第一帧呈现在屏幕上）并调用 trackPlay：
```
- (void)onVideoPlay:(NSNotification *)notification { 
    [_mediaHeartbeat trackPlay]; 
}
```
跟踪播放的结束事件

识别视频播放器中的视频播放结束事件（用户一直观看至内容的结尾）并调用 trackComplete：
```
- (void)onVideoComplete:(NSNotification *)notification { 
    [_mediaHeartbeat trackComplete]; 
}
```
跟踪会话的结束事件

识别视频播放器中的视频播放卸载/关闭事件（用户关闭视频和/或视频已结束并卸载）并调用 trackSessionEnd：
```
- void)onMainVideoUnloaded:(NSNotification *)notification { 
    [_mediaHeartbeat trackSessionEnd]; 
}
```
重要

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

识别视频播放器中的视频暂停事件并调用 trackPause：
```
- (void)onVideoPause:(NSNotification *)notification { 
    [_mediaHeartbeat trackPause]; 
}
```
暂停方案

识别视频播放器将会暂停的任何方案，并确保正确调用了 trackPause。以下方案均要求应用程序调用 trackPause()：
- 用户在应用程序中明确点击暂停。
- 播放器自行进入暂停状态。
- （移动设备应用程序）- 用户将应用程序置于后台，但您希望应用程序保持会话打开。
- （移动设备应用程序）- 出现导致应用程序被置于后台的任何类型的系统中断。例如，用户接收到一个调用，或者出现来自其他应用程序的弹出窗口，但您希望应用程序将会话保持活动状态，以便用户有机会从中断点继续观看视频。
识别播放器中的视频播放事件和/或视频在暂停后继续播放的事件并调用 trackPlay：
```
- (void)onVideoPlay:(NSNotification *)notification { 
    [_mediaHeartbeat trackPlay]; 
}
```
小贴士

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