IOS-VOD SDK

1 概述

针对部分客户希望在使用我公司的点播服务的同时，能快速实现自己的app，特别是对于开发人员资源不足的公司，他们希望更快的集成点播模块到app中。为此，特提供iOS VodSDK，以便客户可以快速实现点播功能。

2 SDK 使用准备

2.1 温馨提示

欢迎客户公司开发人员随时和我们沟通，在相互理解的基础上，共同配合完成开发任务。但是为了提高开发效率，恳请客户公司开发人员在开发之前和开发过程中仔细阅读开发文档和查看Demo代码。如果发现文档中有难以理解或者文档中没有记载的问题，请随时找相关负责人沟通。

Demo中的代码用以示范SDK中的接口调用。不保证最符合客户的需求。请勿照抄Demo中的代码，请在理解SDK机制的基础上修改。如果发现任何疑似bug的现象，欢迎及时与相关负责人沟通。

如果在Demo中发现了bug或者发现了SDK的bug，在告知我公司开发人员时，请将系统版本，硬件版本，产生bug的操作流程一并告知我公司开发人员，必要时需要提供日志。

2.2 工程设置

1 请将工程中的AppDelegate.m改成AppDelegate.mm 或在other link flag里设置-lc++

2 支持系统ios8+

2.3 需要添加的库

系统库

OpenAL.framework

libz.dylib

libiconv.dylib

libsqlite3.dylib

GLKit.framework

点播库

VodSDK.framework

2.4 需要添加的其他资源

将com.gensee.VodSDK.docset 文件放到 ~/Library/Developer/Shared/Documentation/DocSets中，这样在开发的过程中就可以用Xcode自带的文档查看器来查看VodSDK详细的接口文档了。可以按快捷键调出文档查看器 shft+command+0。

3 SDK快速入门

考虑到很多用户在看文档时不知道从何开始，现在在这里写一个快速搭建点播的教程。首先我们实现一个将服务端的点播件（录制件）下载到本地的简易Demo

第一步：新建一个工程， 取名为VodSDKDemo

 

 

第二步： 按照文档中使用准备章节中所述，把所有的库和资源添加到工程, 并将AppDelegate.m 改为AppleDelegate.mm

 

 

第三步：创建点播下载管理器实例，添加将要下载的点播件（录制件）

在viewDidLoad 方法中创建VodDownLoader的实例，将它的代理（delegate）设置成该ViewController，用来接受相关操作后产生的回调（我们绝大部分接口都是采用异步＋回调的模式）。并且用相应参数连接对应的直播。如图

 

 

这里在真正下载之前会保存一些点播件的参数到本地，所需要的参数为：

1.) domain即域名,不能为空;

2.) serType为服务类型，如果你的站点是webcast那么就要设置为webcast，如果是training，则设置为training。

3.) number即编号

4.) loginName 为登录用户名

5.) vodPassword 即观看密码

6.)loginPassword 为登录密码

7.)vodid 为点播件（录制件）ID

8.)downFlag  标志量表示当前添加的点播件是否需要下载

这些参数都可以在类似于下图这样的页面中找到

 

 

3.上图中有个代理方法onAddItemResult:voditem:，反馈添加结果的。正常情况下，会返回了RESULT_SUCCESS，就表明添加成功了，在添加成功后，就可以进行下载了，如果想监听下载的一些事件，请实现其他的代理，比如开始下载，暂停下载，下载进度，下载出错，下载完成等。

第四步：开始下载

在完成了第三步成功之后，就可以进行下载了，如果想监听下载的一些事件，请实现其他的代理，比如开始下载，暂停下载，下载进度，下载出错，下载完成等。

 

 

第五步：播放点播件（录制件）

播放有两种形式，一种是播放本地的点播件（录制件），即已经下载完成的，还有一种是直接在线播放。控制播放要用到VodPlayer这个类。还有一个类VodManage是管理本地点播件信息的也会用到。你可以在添加成功的回调里开始播放，也可以通过点播件ID在本地找到downItem，然后在播放。

 

4 代码示例

参见SDKDemo，SDKDemo只是示范SDK中接口的使用方式，并不保证使用方式最符合用户的需求，请用户在充分理解SDK机制的前提下，根据自己的情况处理数据。对照抄SDKDemo代码引起的性能问题和其他非SDK bug，不负任何责任。

5 SDK中的类

5.1 VodDownLoader

无论是在线播放点播，还是下载点播，都需要先调用addItem:方法校验权限，添加参数到本地，如果是离线播放，则先用VodManage的findDownItem方法在本地搜索是否已经添加过该点播的参数，如果找到了则直接使用downItem参数用于离线播放。下载的事件从VodDownLoadDelegate中返回。

5.1.1 初始化init

使用默认初始化方法[VodDownLoader alloc]init]

5.1.2 设置代理 @property(nonatomic,weak)id<VodDownLoadDelegate>  delegate;

只有正确设置代理后，下载的回调事件才会正确的从代理方法中返回。

5.1.3 是否采用https接口访问@property (nonatomic, assign) BOOL httpAPIEnabled;

默认为NO，走https接口。

因为Apple的要求，内置http请求全部需要换成https的，现在有两种方案可选：

1. 将此参数设置为YES，强制走http接口，但是在程序的info.plist中将我们的域名加入到白名单中。

2. 设置为NO，全部走https接口。

目前第一种方案更加稳定保险，建议选择方案一。

5.1.4 添加到下载- (void)addItem:(VodParam*)vodParam

这一步将会去服务器校验权限，获取点播的信息并存在本地，addItem的结果将从代理中返回

- (void) onAddItemResult:(RESULT_TYPE)resultType voditem:(downItem*)item;

这是下载和在线播放时需要走的第一步，只有返回成功才能继续下载或者在线观看。

如果是要离线播放，只需要用VodManage类找到本地已经下载完成的点播即可，不需要再调用此方法。

5.1.5 获取即将下载的点播的大小@property (nonatomic, assign) BOOL vodTimeFlag;

如果需要获取点播件的大小信息，需要将此属性设置为YES。

5.1.6 开始下载- (void)download:(downItem*)vodItem chatPost:(BOOL)chatPost

在addItem:成功后，可以正式下载点播，chatPost参数表示要将聊天数据按播放时间顺序推送，点播中的聊天可以使用接口一次性全部获取，也可以按播放时间轴按顺序推送。类似方法：- (void)start:(NSString*)downloadID chatPost:(BOOL)chatPost;

5.1.7 停止下载- (void)stop:(NSString*)downloadID;

不要在任何下载事件代理中调用此方法，此方法一般的用法是让用户点击暂停或者停止下载。

 

5.2 VodDownLoadDelegate

下载中产生的事件回调将从代理中返回，不要在任何回调中调用VodDownLoader的stop：方法

5.2.1 添加到下载- (void) onAddItemResult:(RESULT_TYPE)resultType voditem:(downItem*)item;

addItem：返回的结果，如果成功则继续调用下载，或者在线播放。失败则报错。

Result_TYPE:

RESULT_ROOM_NUMBER_UNEXIST	点播不存在
RESULT_SUCCESS	成功
RESULT_NOT_EXSITE	点播不存在
RESULT_FAIL_WEBCAST	点播不存在
RESULT_FAIL_TOKEN	观看口令错误
RESULT_FAIL_LOGIN	登录失败
RESULT_ISONLY_WEB	只支持web观看
RESULT_ROOM_UNEABLE	点播间不可用
RESULT_OWNER_ERROR	内部错误
RESULT_INVALID_ADDRESS	无效地址
RESULT_ROOM_OVERDUE	点播过期
RESULT_AUTHORIZATION_NOT_ENOUGH	授权不够
RESULT_INIT_DOWNLOAD_FAILED	现在初始化失败
RESULT_FAILED_NET_REQUIRED	网络错误
RESULT_UNSURPORT_MOBILE	不支持移动设备

5.2.2  下载开始回调- (void) onDLStart:(NSString*) downloadID

5.2.3 下载出错回调- (void) onDLError:(NSString*) downloadID Status:(VodDownLoadStatus) errorCode;

VodDownLoadStatus

ERROR_NET	网络错误
FALED_TO_WRITE	写文件失败，一般是手机空间不足

 

5.2.4 下载进度回调- (void) onDLPosition:(NSString*) downloadID percent:(float) percent;

Percent为百分比的纯数值，若返回18.0 ，则表示已经在了18%。

5.2.5 停止下载回调- (void) onDLStop:(NSString*) downloadID;

5.2.6 下载完成- (void) onDLStop:(NSString*) downloadID;

 

5.3 VodManage

管理本地点播项，可以通过接口获取本地各种下载状态的点播项，其中添加的点播是需要下载的还是只用于在线观看的，依据addItem:时的参数vodParam里的downFlag字段

5.3.1 初始化方法+ (id)shareManage;

5.3.2 根据ID找到本地的点播-(downItem*)findDownItem:(NSString*)downLoadId

5.3.3 获取已添加的点播列表- (NSArray *)getListDownItem;

5.3.4 获取未下载完的点播列表- (NSArray *)getListOfUnDownloadedItem;

5.3.5 获取所有需要下载的点播列表- (NSArray*)searchAllNeedDownloadItems;

5.3.6 获取需要下载且未下载完的点播- (NSArray*)searchNeedDownloadAndUnFinishedItems;

5.3.7 获取不需要下载，只用于在线观看的点播- (NSArray*)searchUnNeedDownloadItems;

5.3.8 获取下载完成的点播- (NSArray*)searchFinishedItems;

5.3.9 删除本地所有点播- (BOOL)deleteAllItem;

5.3.10 删除某个点播- (BOOL)deleteItem:(NSString*)DownloadId;

5.3.11 更新某个点播信息- (BOOL)updateItem:(downItem*)item;

5.3.12 更新所有点播信息- (BOOL)updateAllItemState:(DOWNSTATE)oldState  toState:(DOWNSTATE) newState;

 

5.4 VodPlayer

主要管理点播播放，在线播放和本地播放需要使用不同的方法，

1. 创建VodPlayer实例

2. 把需要播放的点播（downItem）设置给VodPlayer实例

3. 创建VodGLView和GSVodDocView实例，设置给VodPlayer，用于显示视频文档

4. 调用对应的播放方法进行播放

5. 获取点播的聊天和问答数据或者设置播放方法的postChat参数，使聊天按时间推送

5.4.1 初始化- (id)init

5.4.2 设置要播放的点播@property(nonatomic,strong)downItem *playItem;

5.4.3 设置播放事件代理@property(nonatomic,weak)id<VodPlayDelegate> delegate;

5.4.4 设置视频视图@property(nonatomic,strong)VodGLView *mVideoView;

5.4.5 设置文档视图@property(nonatomic,strong)GSVodDocView *docSwfView;

5.4.6 设置硬解编码@property (assign, nonatomic) BOOL hardwareAccelerate;

5.4.7 设置是否使用flv格式播放@property (assign, nonatomic) BOOL flvEnabled;

5.4.8 开始在线播放- (void)OnlinePlay:(BOOL)postChat audioOnly:(BOOL)audioOnly;

5.4.9 开始离线播放- (void)OfflinePlay:(BOOL)postChat;

5.4.10 加速播放- (void)SpeedPlay:(SpeedValue)value;

 

SpeedValue

SPEED_NORMAL	正常速度
SPEED_125	1.25倍速率
SPEED_150	1.5倍速率
SPEED_175	1.75倍速率
SPEED_2	2倍速率
SPEED_25	2.5倍速率
SPEED_3	3倍速率
SPEED_35	3.5倍速率
SPEED_4	4倍速率

 

5.4.11 暂停播放- (void)pause;

5.4.12 继续播放- (void)resume

5.4.13 停止播放- (void)stop

5.4.14 定位播放- (int)seekTo:(int)position

5.4.15 开关视频- (void)closeVideo:(BOOL)close;

关闭视频后不再产生视频相关的流量。

5.4.16 获取点播的聊天信息- (void)getChatListWithPageIndex:(int)pageIndex;

5.4.17 获取点播的问答信息- (void)getQaListWithPageIndex:(int)pageIndex;

5.4.18 主动发起重连- (void)reconnect;

在检测到3g/4g wifi切换时，主动调用此方法重连

5.4.19 处理和其他音频App交互- (void)resetAudioPlayer;

监听AudioSeesionInterrupt事件，在打断之前调用此方法，防止程序回来之后没有声音。

相关代码：

    [[NSNotificationCenter defaultCenter] addObserver:self

                                             selector:@selector(_onAudioSessionEvent:)

                                                 name:AVAudioSessionInterruptionNotification

                                               object:nil];

 

- (void)_onAudioSessionEvent:(NSNotification*)notification {

    //Check the type of notification, especially if you are sending multiple AVAudioSession events here

    if ([notification.name isEqualToString:AVAudioSessionInterruptionNotification]) {

        NSLog(@"Audio Interruption notification received!");

        //Check to see if it was a Begin interruption

        if ([[notification.userInfo valueForKey:AVAudioSessionInterruptionTypeKey] isEqualToNumber:[NSNumber numberWithInt:AVAudioSessionInterruptionTypeBegan]]) {

            NSLog (@"Audio Interruption began!");

        } else {

            NSLog (@"Audio Interruption ended!");

        }

    }

}

5.4.20 后台播放- (void)enableBackgroundMode;

首先需要在Xcode工程中设置允许app在后台播放，如果app在其他地方设置了AVAudioSession导致无法在后台播放

需要主动调用此方法把AVAudioSession设置回支持后台播放的模式。

 

5.5 VodPlayDelegate

5.5.1 初始化播放回调- (void) onInit:(int) result haveVideo:(BOOL)haveVideo duration:(int)duration docInfos:(NSArray*)docInfos

初始化VodPlayer代理在调用VodPlayer的OnlinePlay和OfflinePlay时返回。Duration：点播件（录制件）总长度，单位：毫秒。为了优化视频加载速度，不再等文档加载，所以此处的文档有可能还并未下载好，docInfos可能是空，随后会从onDocInfo:回调。

Result：

0	成功
0x0c	并发满
10015	已下载的点播文件不完整

 

5.5.2 文档信息回调- (void)onDocInfo:(NSArray*)docInfos;

如果文档信息在onInit方法中返回时空的，则会从这里返回文档信息。

5.5.3 - (void)onRecordInfo:(NSString*)storage duration:(NSString*)duration startTime:(NSString*)startTime;

点播信息回调，大小，时长，开始时间

5.5.4 播放进度回调- (void) onPosition:(int) position;

5.5.5 播放时当前文档信息回调- (void) onPage:(int) position width:(unsigned int)width height:(unsigned int)height;

如果app需要显示相关文档标题，需要用positton去匹配之前返回的docInfos中的信息

5.5.6 缓冲回调- (void) OnBuffer:(BOOL)bBeginBuffer;

bBeginBuffer代表缓冲开始和缓冲结束

5.5.7 定位播放回调- (void) onSeek:(int) position ;

调用VodPlayer 的seekTo方法会产生此回调

5.5.8 视频开始- (void) onVideoStart;

5.5.9 聊天按播放时序推送- (void) OnChat:(NSArray*)chatArray;

VodPlayer的OnlinePlay和OfflinePlay的chatPost参数设置为YES才会推送

5.5.10 获取聊天列表- (void) vodRecChatList:(NSArray*)chatList more:(BOOL)more  currentPageIndex:(int)pageIndex;

一次性获取所有聊天，如果more＝YES，再调用一次获取聊天的接口可获取下一页的聊天

5.5.11 获取问答列表- (void) vodRecQaList:(NSArray*)qaList more:(BOOL)more currentPageIndex:(int)pageIndex;

列表数据 （answer：回答内容 ; answerowner：回答者 ; id：问题id ;qaanswertimestamp:问题回答时间 ;question : 问题内容  ，questionowner:提问者 questiontimestamp：提问时间）

如果more＝YES，再调用一次获取聊天的接口可获取下一页的问答

5.5.12 聊天审核信息回调- (void) OnChatCensor:(NSArray*)censorArray;

根据返回的内容，屏蔽掉聊天中对应的数据。

播放结束回调- (void) onStop;

5.5.13 音频电频值- (void) onAudioLevel:(int) level;

 

5.6 VodParam

点播的参数

5.6.1 域名（必填）@property (nonatomic, copy) NSString *domain;

5.6.2 点播ID（必填）@property (nonatomic, copy) NSString *vodID;

5.6.3 点播编号（建议使用ID）@property (nonatomic, copy) NSString *number;

5.6.4 观看密码（必填）@property (nonatomic, copy) NSString *vodPassword;

5.6.5 昵称（必填）@property (nonatomic, copy) NSString *nickName;

5.6.6 登录用户名@property (nonatomic, copy) NSString *loginName;

登录站点用户名，若后台设置为不用登录 也可观看则不需要此参数

5.6.7 登录密码@property (nonatomic, copy) NSString *loginPassword;

登录站点密码，若后台设置为不用登录 也可观看则不需要此参数

5.6.8 是否使用老版本API@property (nonatomic, assign) BOOL oldVersion;

是否采用老的接口，默认为NO，一般情况下请不要设置为YES

5.6.9 第三方验证@property (nonatomic, copy) NSString *thirdToken;

第三方验证token，配合后台设置使用，若后台无设置，则不需要填写，若oldVersion为YES，则此参数不起作用

5.6.10 自定义userID@property (nonatomic, assign) long long  customUserID;

自定义用户ID，无特殊要求不需要设置，平台会自动分配，若要设置，请设置为大于十亿的数字

5.6.11 是否为Box用户@property (nonatomic, assign) BOOL isBox;

是否为Box客户，默认为NO， 一般客户不需要设置， Box客户为后台单独部署，不和我们的站点一起更新，Box客户的域名一般不是 “*.gensee.com”

5.6.12 是否需要下载（必填）@property (nonatomic, assign) int downFlag;

是否需要下载，1需要，0不需要

5.6.13 服务类型（必填）@property (nonatomic, copy) NSString *serviceType;

服务类型：webcast或者training

6 常见的问题

6.1 我该如何填写参数，使Demo正确运行？

请开发人员联系负责和我公司交接直播端（网页入口，启动的PC客户端）的同事，让他提供对应的参数信息。