iOS OpenSDK对接文档
iOS LCOpenSDK作为一整套接入乐橙云的客户端接入框架,可以使开发者在自身iOS应用中快速集成乐橙云视频能力,本OpenSDK只含真机调试的功能,不支持任何模拟器调试,支持Xcode 9.0以上。
1. OpenSDK安装
OpenSDK的安装分为两种方式:通过cocoapods安装和手动从官网下载压缩包安装
1.1 CocoaPods 安装
1.1.1 CocoaPods引入
在Podfile文件中添加pod 'LCOpenSDK'语句
执行pod install
备注:如果不能引入则可能是需要更新本地仓库,需执行pod repo update。
安装成功后如下图:
1.1.2 路径配置
Framework路径:Build Setting->Search Paths->Framework Search Paths添加:
$(PROJECT_DIR)/Pods/LCOpenSDK/Framework
头文件路径:Build Setting->Search Paths->Header Search Paths添加:
$(PROJECT_DIR)/Pods/LCOpenSDK/Framework/LCOpenSDKDynamic.framework/Headers/LCOpenSDK
$(PROJECT_DIR)/Pods/LCOpenSDK/Framework/LCOpenSDKDynamic.framework/Headers/LCOpenNetSDK
$(PROJECT_DIR)/Pods/LCOpenSDK/Framework/LCOpenSDKDynamic.framework/Headers/LCOpenApi
Build Settings->Build Options ->Enable Bitcode设置为NO
1.2 压缩包安装
通过乐橙云开放平台官网下载IOS版本的OpenSDK压缩包到本地进行手动引入,此时引入时要十分注意SDK的路径,以demo为例,OpenSDK位于工程目录下的Depend文件夹下面。
1.2.1 路径配置
Framework路径:Build Setting->Search Paths->Framework Search Paths添加:
$(PROJECT_DIR)/Depend
头文件路径:Build Setting->Search Paths->Framework Search Paths添加:
$(PROJECT_DIR)/Depend/LCOpenSDKDynamic.framework/Headers
$(PROJECT_DIR)/Depend/LCOpenSDKDynamic.framework/Headers/LCOpenSDK
$(PROJECT_DIR)/Depend/LCOpenSDKDynamic.framework/Headers/LCOpenNetSDK
$(PROJECT_DIR)/Depend/LCOpenSDKDynamic.framework/Headers/LCOpenApi
路径:Build Phases->Embed Frameworks添加:
LCOpenSDKDynamic.framework,Destinations选择Frameworks。
备注:$(PROJECT_DIR)为Demo工程所在目录,按要求添加LCOpenSDKDemo和Depend文件夹(对应iOS_demo和iOS_sdk文件夹);Build Phases ->Embed Frameworks路径如果不存在选择左上角加号,然后选择NEW Copy Files Phase进行添加, 最后双击修改名称为Embed Frameworks。
1.2.2 系统库配置
在工程TARGETS->Build Phases->Link Binary With Libraries下添加如下系统库:
CoreAudio.framework
MediaPlayer.framework
AudioToolbox.framework
VideoToolbox.framework
OpenGLES.framework
MediaAccessibility.framework
CoreVideo.framework
AVFoundation.framework
CoreMedia .framework
libz.tbd(libz.dylib)
配置后如下图:
1.3 权限申请与配置
SDK使用需配置相关系统权限,主要包含以下:
相册权限:NSPhotoLibraryUsageDescription
照片存储权限:NSPhotoLibraryAddUsageDescription
麦克风权限:NSMicrophoneUsageDescription
相机权限:NSCameraUsageDescription
本地网络权限:NSLocalNetworkUsageDescription
地理位置权限:NSLocationUsageDescription
备注:设备配网另需组播权限,需从苹果开发者中心申请。
2. 初始化
2.1 OpenSDK初始化
在使用OpenSDK相关功能前需要先进行OpenSDK初始化,初始化涉及开发者用户授权token和平台地址信息,初始化操作主要依赖于我们开放的LCOpenSDK_Api类。
具体代码实现可参考下面:
/** 初始化平台信息 */
LCOpenSDK_ApiParam * apiParam = [[LCOpenSDK_ApiParam alloc] init];
/** 1. 设置协议 */
apiParam.procotol = PROCOTOL_TYPE_HTTPS;
/** 2. 设置乐橙云平台服务地址 */
apiParam.addr = @"openapi.lechange.cn";
/** 3. 设置服务端口 */
apiParam.port = 443;
/** 4. 设置token,token根据AppId和AppSecret调用乐橙云开放平台获取 */
apiParam.token = @"********";
/** 5. 调用SDK接口进行初始化平台信息 */
LCOpenSDK_Api* m_hc = [[LCOpenSDK_Api shareMyInstance] initOpenApi:apiParam];
备注:开放平台获取Token:获取管理员token 或者 获取子用户token
2.2 配置OpenSDK日志级别
OpenSDK提供了日志打印的类LCOpenSDK_Log,开发者可以选择配置合适的日志级别,默认等级为LogLevelTypeFatal。
// 初始化LCOpenSDK_LogInfo实例对象
LCOpenSDK_LogInfo *info = [LCOpenSDK_LogInfo new];
// 赋值日志等级字段
info.levelType = LogLevelTypeDebug;
// LCOpenSDK_LogInfo实例配置日志等级
[[LCOpenSDK_Log shareInstance] setLogInfo:info];
LogLevelType参数说明:
LogLevelTypeFatal = 1,// 重大错误
LogLevelTypeError,// 错误信息
LogLevelTypeWarning,// 警告信息
LogLevelTypeInfo,// 主要用于生产环境中输出程序运行的一些重要信息
LogLevelTypeDebug// 运行调试信息
备注:在排查一些SDK内部问题时可以调整SDK日志级别完成问题复现与日志抓取,方便后续的问题定位和分析
3. 设备添加功能
无线配网是OpenSDK基础功能之一,和无线配网结合一起使用的还有设备搜索,设备初始化等,无线配网目前OpenSDK支持SmartConfig和软AP配网两种方式,不同设置支持的配网方式不同,具体采用哪种配网方式,需要根据设备型号进行确定。
3.1 SmartConfig配网添加
获取设备信息;扫描标签或者手动输入
调用unBindDeviceInfo接口查询设备配网方式和绑定状态
检测设备是否绑定
判断是否支持smartConfig配网
开始无线配网
开始局域网内搜索设备初始化信息
搜索到设备,停止搜索
初始化设备
调用deviceOnline查询设备状态
查询到设备在线,调用bindDevice接口进行绑定设备
代码实现如下:
/** 1.初始化LCOpenSDK_ConfigWIfi对象 */
LCOpenSDK_ConfigWIfi *m_configWifi = [[LCOpenSDK_ConfigWIfi alloc] init];
/**
2.开始配网
devId:设备序列号
ssid: wifi名称
password:wifi密码
security: 安全码,SC码设备需要,非SC设备传@“”
*/
NSInteger iRet = [m_configWifi configWifiStart:@"********"
ssid:@"********"
password:@"********"
secure:@"********"
voiceFreq:11000];
if (iRet < 0) {
NSLog(@"smartconfig failed\n");
}
__block NSString *theMac = nil; /** 设备mac地址 */
__block NSString *theIp = nil; /** 设备ip */
__block int thePort = 0; /** 设备端口 */
__block int theInitStatus = 0; /** 设备初始化信息,0:不需要初始化, 1:需要初始化且未初始化 2:需要初始化且已初始化 */
/** 3.初始化设备初始化信息 */
LCOpenSDK_DeviceInit *deviceInit = [[LCOpenSDK_DeviceInit alloc] init];
/** 4.搜索设备初始化信息 */
[deviceInit searchDeviceInitInfo:@"********" timeOut:60000*2 success:^(LCOPENSDK_DEVICE_INIT_INFO info) {
theMac = [NSString stringWithUTF8String:info.mac];
theIp = [NSString stringWithUTF8String:info.ip];
thePort = info.port;
theInitStatus = info.status;
}];
if (!theMac || !theIp) {
NSLog(@"Search device init info failed!\n");
}
/** 5.停止配网 */
[m_configWifi configWifiStop];
/** 6.初始化状态为1且不是SC码设备,进行初始化, 初始化密码可根据需要自己设置 */
int ret = [deviceInit initDevice:theMac password:@"********" ip:theIp];
if (-2 == ret) {
NSLog(@"Init device failed!\n");
}
3.2 软AP配网添加
获取设备信息;扫描标签或者手动输入
调用unBindDeviceInfo接口查询设备配网方式和绑定状态
检测设备是否绑定
判断是否支持SoftAP配网
连接设备热点
开始搜索设备,搜索到设备,直接绑定
开始SoftAP配网
配网成功,停止搜索
调用deviceOnline查询设备状态
查询到设备在线,调用bindDevice接口进行绑定设备
代码实现如下:
/** 1.初始化设备初始化对象 */
LCOpenSDK_DeviceInit *m_deviceInit = [[LCOpenSDK_DeviceInit alloc] init];
/** 2.搜索设备初始化信息信息 */
__block int m_initDevStatus = 0;
[m_deviceInit searchDeviceInitInfo:@"********" timeOut:10*1000 success:^(LCOPENSDK_DEVICE_INIT_INFO info) {
m_initDevStatus = info.status;
}];
/** 3. 初始化软Ap配网对象 */
LCOpenSDK_SoftAP *m_softAP = [[LCOpenSDK_SoftAP alloc] init];
/** 4. 初始化状态m_initDevStatus为0或者为SC码设备,直接软Ap配网,设备密码传@“admin”;初始化状态m_initDevStatus为1,设备密码自定义; SC码设备需要穿设备安全码,isSC设为YES */
NSInteger softAPResult = [m_softAP startSoftAPConfig:@"********" wifiPwd:@"********" deviceId:@"********" devicePwd:@"admin" isSC:NO];
if (softAPResult < 0) {
NSLog(@"SoftAP failed!\n");
}
4. 实时预览
实时预览的主要步骤有:
通过乐橙云平台设备查询接口获取设备信息。
调用OpenSDK接口进行播放窗口初始化设置以及监听设置。
具体代码实现参考下面:
/** 1. 初始化播放窗口信息,包括位置大小以及索引 */
LCOpenSDK_PlayWindow *m_play = [[LCOpenSDK_PlayWindow alloc] initPlayWindow:CGRectMake(0, 0, 400, 300) Index:0];
/** 2. 设置播放窗口背景色 */
[m_play setSurfaceBGColor:[UIColor blackColor]];
/** 3. 添加播放窗口到父视图 */
[self.view addSubview:[m_play getWindowView]];
/** 4. 设置监听对象,可监听播放结果回调 */
[m_play setWindowListener:(id<LCOpenSDK_EventListener>)self];
- 调用OpenSDK接口进行播放参数设置,然后开始播放。
具体代码实现参考下面:
/** 1. 初始化实时预览播放参数对象 */
LCOpenSDK_ParamReal *paramReal = [[LCOpenSDK_ParamReal alloc] init];
/** 2. 设置token,token根据AppId和AppSecret调用乐橙云开放平台获取 */
paramReal.accessToken = @"********";
/** 3. 设置设备序列号 */
paramReal.deviceID = @"********";
/** 4. 设置设备通道,对于单通道设备为0, 对于NVR等多通道设备为具体通道号 */
paramReal.channel = 0;
/** 5. 设置码流模式,支持主码流和子码流 */
paramReal.defiMode = DEFINITION_MODE_HG;
/** 6. 设置密钥,如果为用户自定义密钥为具体密钥, 非用户自定密钥可为设备序列号*/
paramReal.psk = @"********";
/** 7. 设置播放密钥,非必传,传了会提升拉流速度 */
paramReal.playToken = @"********";
/** 8. 是否走拉流优化,YES会提升拉流速度,建议传YES即可 */
paramReal.isOpt = YES;
/** 8. 开始播放 */
[m_play playRtspReal:paramReal];
- 实现监听回调。
具体代码实现参考下面:
/** 1. 播放结果回调,可根据错误码进行不同处理 */
- (void)onPlayerResult:(NSString*)code Type:(NSInteger)type Index:(NSInteger)index {
}
/** 2. 播放开始回调 */
- (void)onPlayBegan:(NSInteger)index {
}
5. 录像回放
录像回放是对设备存储在SD卡以及硬盘上的录像或云存储上的录像进行播放的的功能,针对设备录像和云存储录像,OpenSDK提供了不同的接口,使用时要注意。
对于设备本地录像播放,OpenSDK提供了两个接口,分别为按文件名播放和按时间播放,使用过程可根据不同场景需要进行使用,推荐使用按文件名播放。
实时预览的主要步骤有:
具体代码实现参考下面:
/** 1. 初始化播放窗口信息,包括位置大小以及索引 */
LCOpenSDK_PlayWindow *m_play = [[LCOpenSDK_PlayWindow alloc] initPlayWindow:CGRectMake(0, 0, 400, 300) Index:0];
/** 2. 设置播放窗口背景色 */
[m_play setSurfaceBGColor:[UIColor blackColor]];
/** 3. 添加播放窗口到父视图 */
[self.view addSubview:[m_play getWindowView]];
/** 4. 设置监听对象,可监听播放结果回调 */
[m_play setWindowListener:(id<LCOpenSDK_EventListener>)self];
- 调用OpenSDK接口进行播放参数设置,然后开始播放。
具体代码实现参考下面:
1.设备录像按文件名播放:
/** 1. 初始化按文件名播放参数对象 */
LCOpenSDK_ParamDeviceRecordFileName * paramDeviceRecord = [[LCOpenSDK_ParamDeviceRecordFileName alloc] init];
/** 2. 设置token,token根据AppId和AppSecret调用乐橙云开放平台获取 */
paramDeviceRecord.accessToken = @"********";
/** 3. 设置设备序列号 */
paramDeviceRecord.deviceID = @"********";
/** 4. 设置设备通道,对于单通道设备为0, 对于NVR等多通道设备为具体通道号 */
paramDeviceRecord.channel = 0;
/** 5. 设置密钥,如果为用户自定义密钥为具体密钥, 非用户自定密钥可为设备序列号 */
paramDeviceRecord.psk = @"********";
/** 6. 设置播放密钥,非必传,传了会提升拉流速度 */
paramDeviceRecord.playToken = @"********";
/** 7. 设置录像名即录像Id(recordId) */
paramDeviceRecord.fileName = @"********";
/** 8. 设置播放偏移时间,单位为秒,从文件开始播放设置为0即可 */
paramDeviceRecord.offsetTime = 0 ;
/** 9. 是否走拉流优化,YES会提升拉流速度,建议传YES即可 */
paramDeviceRecord.isOpt = YES;
/** 10. 开始播放 */
[m_play playDeviceRecordByFileName:paramDeviceRecord];
2.设备录像按时间播放:
/** 1. 初始化按时间播放参数对象 */
LCOpenSDK_ParamDeviceRecordUTCTime *paramDeviceRecordUTCTime = [[LCOpenSDK_ParamDeviceRecordUTCTime alloc] init];
/** 2. 设置token,token根据AppId和AppSecret调用乐橙云开放平台获取 */
paramDeviceRecordUTCTime.accessToken = @"********";
/** 3. 设置设备序列号 */
paramDeviceRecordUTCTime.deviceID = @"********";
/** 4. 设置设备通道,对于单通道设备为0, 对于NVR等多通道设备为具体通道号 */
paramDeviceRecordUTCTime.channel = 0;
/** 5. 设置码流模式,支持主码流和子码流 */
paramDeviceRecordUTCTime.defiMode = DEFINITION_MODE_HG;
/** 6. 设置密钥,如果为用户自定义密钥为具体密钥, 非用户自定密钥可为设备序列号 */
paramDeviceRecordUTCTime.psk = @"********";
/** 7. 设置播放密钥,非必传,传了会提升拉流速度 */
paramDeviceRecordUTCTime.playToken = @"********";
/** 8.录像的开始时间,不为0 */
paramDeviceRecordUTCTime.beginTime = 0;
/** 9.录像的结束时间,不为0 */
paramDeviceRecordUTCTime.endTime = 0;
/** 10. 是否走拉流优化,YES会提升拉流速度,建议传YES即可 */
paramDeviceRecordUTCTime.isOpt = YES;
/** 11. 开始播放 */
[m_play playDeviceRecordByUtcTime:paramDeviceRecordUTCTime];
3.云存储录像播放:
/** 1. 初始化云存储录像播放参数对象 */
LCOpenSDK_ParamCloudRecord *paramCloudRecord = [[LCOpenSDK_ParamCloudRecord alloc] init];
/** 2. 设置token,token根据AppId和AppSecret调用乐橙云开放平台获取 */
paramCloudRecord.accessToken = @"********";
/** 3. 设置设备序列号 */
paramCloudRecord.deviceID = @"********";
/** 4. 设置设备通道,对于单通道设备为0, 对于NVR等多通道设备为具体通道号 */
paramCloudRecord.channel = 0;
/** 5. 设置密钥,如果为用户自定义密钥为具体密钥, 非用户自定密钥可为设备序列号 */
paramCloudRecord.psk = @"********";
/** 6. 设置录像Id(recordRegionID)*/
paramCloudRecord.recordRegionID = @"********";
/** 7. 设置播放偏移时间,单位为秒,从文件开始播放设置为0即可 */
paramCloudRecord.offsetTime = 0;
/** 8. 设置录像类型, 设置为RECORD_TYPE_ALL即可 */
paramCloudRecord.recordType = RECORD_TYPE_ALL;
/** 9. 设置播放超时时间, 单位为秒*/
paramCloudRecord.timeOut = 60;
/** 10. 开始播放 */
[m_play playCloudRecord:paramCloudRecord];
- 实现监听回调。
具体代码实现参考下面:
/** 1. 播放结果回调,可根据错误码进行不同处理 */
- (void)onPlayerResult:(NSString*)code Type:(NSInteger)type Index:(NSInteger)index {
}
/** 2. 播放开始回调 */
- (void)onPlayBegan:(NSInteger)index {
}
/** 3. 播放完成回调 */
- (void)onPlayFinished:(NSInteger)index {
}
/** 4. 文件开始时间和结束时间回调 */
- (void)onFileTime:(long)beginTime EndTime:(long)endTime Index:(NSInteger)index {
}
/** 5. 文件播放时间回调 */
- (void)onPlayerTime:(long)time Index:(NSInteger)index {
}
6. 语音对讲
语音对讲是设备和客户端进行语音对讲的功能,在设备进行实时预览的同时,进行语音对讲。
语音对讲功能开发主要分为以下几步:
进行实时预览功能开发。
调用OpenSDK接口初始化语音对讲对象,初始化播放参数对象并设置参数开始对讲。
具体代码实现参考下面:
/** 1. 初始化语音对讲对象 */
LCOpenSDK_AudioTalk *m_talker = [[LCOpenSDK_AudioTalk alloc] init];
/** 2. 设置监听对象 */
[m_talker setListener:(id<LCOpenSDK_TalkerListener>)self];
/** 3. 初始化语音对讲参数对象 */
LCOpenSDK_ParamTalk *paramTalk = [[LCOpenSDK_ParamTalk alloc] init];
/** 4. 设置token,token根据AppId和AppSecret调用乐橙云开放平台获取 */
paramTalk.accessToken = @"********";
/** 5. 设置设备序列号 */
paramTalk.deviceID = @"********";
/** 6. 设置设备通道,-1为设备对讲, 和通道对讲为具体通道号 */
paramTalk.channel = -1;
/** 7. 设置密钥,如果为用户自定义密钥为具体密钥, 非用户自定密钥可为设备序列号 */
paramTalk.psk = @"********";
/** 8. 设置播放密钥,非必传,传了会提升拉流速度 */
paramTalk.playToken = @"********";
/** 9. 是否走拉流优化,YES会提升拉流速度,建议传YES即可 */
paramTalk.isOpt = YES;
/** 10. 开始对讲 */
[m_talker playTalk:paramTalk];
- 实现对讲结果回调。
具体代码实现参考下面:
/** 对讲结果回调 */
-(void) onTalkResult:(NSString *) error TYPE:(NSInteger) type {
}
7. 录像下载
OpenSDK提供了接口供开发者开发设备录像和云存储录像的下载功能,目前接口仅提供MP4格式的录像文件下载,暂不支持其他格式。
语音对讲功能开发主要分为以下几步:
具体代码实现参考下面:
/** 1.路径名称 */
NSArray* paths = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES);
NSString* libraryDirectory = [paths objectAtIndex:0];
NSString* myDirectory = [libraryDirectory stringByAppendingPathComponent:@"lechange"];
NSString* downloadDirectory = [myDirectory stringByAppendingPathComponent:@"download"];
/** 不要每个都一样,否则会覆盖 */
NSString* infoPath = [downloadDirectory stringByAppendingPathComponent:[NSString stringWithFormat:@"record_download"]];
NSString* m_downloadPath = [infoPath stringByAppendingString:@".mp4"];
/** 2.根据路径名称创建路径 */
NSFileManager* fileManage = [NSFileManager defaultManager];
NSError* pErr;
BOOL isDir;
if (NO == [fileManage fileExistsAtPath:myDirectory isDirectory:&isDir]) {
[fileManage createDirectoryAtPath:myDirectory withIntermediateDirectories:YES attributes:nil error:&pErr];
}
if (NO == [fileManage fileExistsAtPath:downloadDirectory isDirectory:&isDir]) {
[fileManage createDirectoryAtPath:downloadDirectory withIntermediateDirectories:YES attributes:nil error:&pErr];
}
/** 3.创建下载对象 */
LCOpenSDK_Download* m_download = [LCOpenSDK_Download shareMyInstance];
/** 4.设置监听 */
[m_download setListener:(id<LCOpenSDK_DownloadListener>)self];
/** 5.开始云录像下载 */
[m_download startDownload:0 filepath:m_downloadPath token:@"********" devID:@"********" channelID:0 psk:@"********" recordRegionId:@"********" Type:1000 Timeout:10];
/** 5.开始设备录像下载,speed下载速度设为16倍速即可,fileID级recordId */
[m_download startDownload:0 filepath:m_downloadPath token:@"********" devID:@"********" decryptKey:@"********" fileID:@"********" speed:16];
- 实现下载回调。
具体代码实现参考下面:
/** 1.下载数据回调 */
- (void) onDownloadReceiveData:(NSInteger)index datalen:(NSInteger)datalen {
}
/** 2.下载状态回调 */
- (void) onDownloadState:(NSInteger)index code:(NSString *)code type:(NSInteger)type {
}
8. 数据解密
目前设备告警缩略图和录像封面图默认是加密存储的,需要解密后才能正常打开展示,使用SDK的LCOpenSDK_Utils类实现图片的解密
具体代码如下:
NSData* dataOut = [[NSData alloc] init];
NSInteger iret = [[LCOpenSDK_Utils new] decryptPic:picData deviceID:deviceId key:key bufOut:&dataOut];
NSLog(@"decrypt iret[%ld]", (long)iret);
if (0 == iret) {
UIImage* img = [UIImage imageWithData:[NSData dataWithBytes:[dataOut bytes] length:[dataOut length]]];
[cache storeImage:img forKey:key_temp toDisk:YES completion:^{
}];
[self setImage:img];
}