接入必读
- 本SDK只包含真机调试的功能，不支持任何模拟器的调试。
- 适时查看萤石开放平台官网的内容更新，特别是FAQ栏目。尽量多使用FAQ，我们对开发过程中遇到的多次被提问的问题进行汇总，FAQ能解决您90%的问题，可以通过关键字进行搜索。
- WiFi配置的流程请参考论坛说明 ，注意设备的状态。
- iOS的demo已经移除了开放平台SDK的静态库和appKey，请将下载的SDK库文件和头文件拷贝到demo工程根目录下的EZOpenSDK文件夹中，并填写官网申请的appKey即可运行代码。
简介
本文档用于说明萤石开放平台SDK iOS版本接口之间的关系以及接口调用顺序，对开放平台SDK iOS版本主要流程都有详细说明和代码示例。主要有功能介绍、安装说明、权限配置和主要流程介绍。
名词解释
| 名词 | 注解 |
|---|---|
| appKey | AppKey的申请可以参阅: 官网 |
| accessToken | 访问令牌，由server返回给client用于认证 |
| expire | accessToken过期时间 |
| DeviceSerial | 设备序列号 |
| CameraNo | 设备通道号 |
| DeviceSerial+CameraNo | 摄像头唯一标志 |
| OSD | 视频视频当前时间 |
| PTZ | 云台控制，可以通过终端控制操作设备 |
功能介绍
| 功能 | 说明 |
|---|---|
| 账号对接(授权登录、sdk接口登录) | 授权到萤石云平台，复用萤石云平台能力 |
| 摄像头列表 | 得到对应账号下设备 |
| 直播预览 | 直播预览，可设置直播分辨率 |
| 查看回放（SD卡、硬盘录像机、云存储） | 回放 |
| 设备对讲 | 对讲（包含半双工对讲和全双工对讲） |
| 设备的设置功能 | 设备设置接口api |
| 设备控制接口（云台、镜头画面） | 云台控制 |
| WiFi配置 | 设备wifi配置 |
| 直播、回放边播边录 | 播放过程中录像 |
| 直播、回放边播边截屏 | 播放过程中截屏 |
| 告警消息 | 告警消息获取 |
安装SDK
SDK安装分为两种方式cocoapods安装和下载完整SDK包安装
cocoapods安装
- 在Podfile文件中添加如下语句
pod 'EZOpenSDK' - 执行
pod install - 关闭目标target的bitcode功能 Build Settings->Enable Bitcode设置为NO
- 安装完成
下载安装
下载SDK并解压缩
创建一个新的XCode工程，然后导入SDK库libEZOpenSDK.a和头文件（如图所示）;
导入openssl依赖库libssl.a、libcrypto.a以及相关的头文件(如图所示);
导入系统依赖库libsqlite3.0、CoreMedia、AudioToolbox、VideoToolbox.framework、GLKit.framework、OpenAL.framework、MobileCoreServices、SystemConfiguration、CoreTelephony、AVFoundation.framework、libc++、libiconv.2.4.0、libbz2、libz(如图所示);
添加Other Linker Flags -ObjC
注意区分大小写。
- 关闭目标target的bitcode功能 Build Settings->Enable Bitcode设置为NO
- 请将 Resources 文件中的 com.hri.hpc.mobile.ios.player.metallib 资源文件加入到 XCode 项目工程中
- 配置完成
权限配置
权限配置是在工程的info.plist文件中进行配置。在Xcode工程的文件导航栏中找到该文件，右键选择Open As -> Source Code,在合适位子添加对应权限代码。
- 相册权限：
如果需要使用开放平台播放器录像和截图并保存的功能，就需要配置相册权限。
<key>NSPhotoLibraryUsageDescription</key> <string>需要使用手机相册</string> <key>NSPhotoLibraryAddUsageDescription</key> <string>需要使用手机相册</string> - 麦克风权限：
如果需要使用设备对讲功能，就需要配置麦克风权限。务必在发起对讲前向iOS系统申请麦克风权限，否则将导致第一次对讲异常。
<key>NSMicrophoneUsageDescription</key> <string>需要使用手机麦克风</string> - 摄像头权限：
如果需要仿照demo实现扫码添加设备功能，就需要配置摄像头权限。
<key>NSCameraUsageDescription</key> <string>需要使用手机照相机</string>
主要流程
初始化流程
上图展示初始化SDK并进行授权登录的流程。
授权登录分为服务端获取accessToken和客户端获取accessToken两种方式。
- 服务端模式：服务端获取accessToken后下发到客户端，客户端直接调用setAccessToken:接口即完成授权登录；
- 客户端模式：客户端调用openLoginPage:接口，block中返回的accessToken不为空即完成授权登录。该模式下SDK内部会自动管理accessToken的有效性，会进行自动刷新等操作，可以用isLogin接口判断是否已登录。
完成授权登录后方可进行关于设备和用户的一系列操作。
示例代码：
初始化SDK
[EZOpenSDK initLibWithAppKey:@"Your App Key"];授权登录流程 服务端模式：
[EZOpenSDK setAccessToken:@"Your accessToken"];客户端模式：
[EZOpenSDK openLoginPage:^(EZAccessToken * accessToken) { }];
直播流程
步骤
第一步创建播放器。可调用createPlayerWithDeviceSerial:cameraNo:方法创建播放器。
第二步配置播放器。播放器创建完成后需要进行设置代理，设置播放视图，验证码设置等配置。
第三步开始播放。调用startRealPlay开启直播。 示例代码：
//创建播放器，也可以直接使用EZPlayer类中的方法创建 EZPlayer *player = [EZOpenSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo]; //可选，建议设置，设置后才可以处理代理方法 player.delegate = self; //可选，设备开启了视频/图片加密功能后需设置，可根据EZDeviceInfo的isEncrypt属性判断 [player setPlayVerifyCode:verifyCode]; //设置用以展示直播画面的视图 [player setPlayerView:playerView]; //开始直播 [player startRealPlay];说明
- 可调用setVideoLevel:cameraNo:videoLevel:completion:接口设置视频清晰度，此调节可以在视频播放前设置也可以在视频播放成功后设置。视频播放成功后设置了清晰度，需要先停止播放stopRealPlay，然后重新开启播放startRealPlay才能生效。
- 开始播放之后在didReceivedMessageCode:中会收到播放开始的消息；失败会在didPlayFailed:收到错误码，如果是错误码EZ_SDK_NEED_VALIDATECODE = 400035(需要设备验证码)或者EZ_SDK_VALIDATECODE_NOT_MATCH = 400036（设备验证码不匹配），需要开发者自己处理让用户输入验证密码，然后调用setPlayVerifyCode:设置密码，然后重新启动播放。
- 同一设备需要开启不同功能（直播/回放/对讲）的播放器时，需要分别对每个功能创建一个播放器。播放器的功能是单一的。
回放流程
步骤
- 第一步创建播放器。可调用createPlayerWithDeviceSerial:cameraNo:方法创建播放器。
- 第二步配置播放器。播放器创建完成后需要进行设置代理，设置播放视图，验证码设置等配置。
第三步开始回放。调用startPlaybackFromCloud:或startPlaybackFromDevice开始回放。 示例代码：
//创建播放器，也可以直接使用EZPlayer类中的方法创建 EZPlayer *player = [EZOpenSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo]; //可选，建议设置，设置后才可以处理代理方法 player.delegate = self; //可选，设备开启了视频/图片加密功能后需设置，可根据EZDeviceInfo的isEncrypt属性判断 [player setPlayVerifyCode:verifyCode]; //设置用以展示直播画面的视图 [player setPlayerView:playerView]; //回放云端存储的视频，cloudFile由searchRecordFileFromCloud:cameraNo:beginTime:endTime:completion:接口获取 [player startPlaybackFromCloud:cloudFile]; //或者 //回放设备上存储的视频，deviceFile由searchRecordFileFromDevice:cameraNo:beginTime:endTime:completion:接口获取 [player startPlaybackFromDevice:deviceFile];说明
- 回放需先获取到视频信息,searchRecordFileFromCloud:cameraNo:beginTime:endTime:completion:方法和searchRecordFileFromDevice:cameraNo:beginTime:endTime:completion:方法分别是获取云端视频列表和设备存储视频列表的两个方法。
- 开始播放之后在didReceivedMessageCode:中会收到播放开始的消息；失败会在didPlayFailed:收到错误码，如果是错误码EZ_SDK_NEED_VALIDATECODE = 400035(需要设备验证码)或者EZ_SDK_VALIDATECODE_NOT_MATCH = 400036（设备验证码不匹配），需要开发者自己处理让用户输入验证密码，然后调用setPlayVerifyCode:设置密码，重新启动播放。
- 同一设备需要开启不同功能（直播/回放/对讲）的播放器时，需要分别对每个功能创建一个播放器。播放器的功能是单一的。
注意：回放结束时存在上报380101错误码的情况，并且播放器不会上报播放结束的消息。此时可调用EZPlayer中的getOSDTime方法获取当前播放时间，用该时间与录像的结束时间进行比较。如果时间点相近则认为播放结束，如果时间点相差较大则为播放错误。从4.8.2版本开始，已在SDK中对种情况进行了自动处理。
录像下载流程
步骤
以云存储录像下载为例：
- 第一步创建下载任务。可调用EZCloudRecordDownloadTask的initTaskWithID:cloudRecordFile:verifyCode:savePath方法创建下载任务。
- 第二步设置回调函数。setDownloadCallBackWithFinshed:failed:方法设置回调。
- 第三步加入下载队列。加入下载队列后开始下载。 示例代码：
//1.创建下载任务
EZCloudRecordDownloadTask *task = [[EZCloudRecordDownloadTask alloc] initTaskWithID:@"2" cloudRecordFile:cloudFile verifyCode:self.verifyCode savePath:path];
//2.设置回调函数
__weak typeof(task) weakTask = task;
[task setDownloadCallBackWithFinshed:^(EZRecordDownloaderStatus statusCode) {
__strong typeof(weakTask) strongTask = weakTask;
NSLog(@"statuCode:%ld", (long)statusCode);
switch (statusCode) {
case EZRecordDownloaderStatusFinish:
//do something
break;
case EZRecordDownloaderStatusMoreToken:
//do something
break;
default:
break;
}
[[EZRecordDownloader shareInstane] stopDownloadTask:strongTask];
} failed:^(NSError * _Nonnull error) {
NSLog(@"EZDeviceRecordDownloader error:%@", error);
__strong typeof(weakTask) strongTask = weakTask;
//do something
[[EZRecordDownloader shareInstane] stopDownloadTask:strongTask];
}];
//3.加入下载队列下载
[[EZRecordDownloader shareInstane] addDownloadTask:task];
说明
- 设备录像下载流程基本相同，但由于底层实现不同，创建任务方法为异步执行，其余操作需要在其回调中进行。
- 设备录像并发下载受设备路数限制，可通过错误码395416和380045判断。
对讲流程
步骤
- 第一步创建播放器。可调用createPlayerWithDeviceSerial:cameraNo:方法创建播放器。
- 第二步配置播放器。播放器创建完成后需要进行设置代理，验证码设置等配置。
第三步开始播放。调用startVoiceTalk开启对讲。 示例代码：
//创建播放器，也可以直接使用EZPlayer类中的方法创建 EZPlayer *talkPlayer = [EZOpenSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo]; //可选，建议设置，设置后才可以处理代理方法 talkPlayer.delegate = self; //可选，设备开启了视频/图片加密功能后需设置，可根据EZDeviceInfo的isEncrypt属性判断 [talkPlayer setPlayVerifyCode:verifyCode]; //发起对讲 [talkPlayer startVoiceTalk]; //停止对讲 [talkPlayer stopVoiceTalk];
半双工对讲在发起对讲成功后，默认模式为 手机端听-设备端说。可进行如下操作进行听说模式切换。
//切换到 手机端说-设备端听 模式
[talkPlayer audioTalkPressed:YES];
//切换到 手机端听-设备端说 模式
[talkPlayer audioTalkPressed:NO];
说明
- 对讲流程需要根据设备的对讲能力进行区分处理。EZDeviceInfo中的isSupportTalk可获取到设备的对讲能力，0-不支持对讲，1-支持全双工对讲，3-支持半双工对讲。
- 同一设备需要开启不同功能（直播/回放/对讲）的播放器时，需要分别对每个功能创建一个播放器。播放器的功能是单一的。
设备添加流程
步骤
第一步查询设备信息。查询设备信息probeDeviceInfo:deviceType:completion:接口所获得对象是EZProbeDeviceInfo，正常查询到设备信息对象说明查询成功，可以直接进行设备添加操作。
第二步配置设备网络。调用startConfigWifi:password:deviceSerial:deviceStatus:进行网络配置。startConfigWifi:password:deviceSerial:deviceStatus:和stopConfigWifi需要成对调用,EZWifiConfigStatus的内容通过回调的block获取，详见demo。
DEVICE_WIFI_CONNECTING = 1, //设备正在连接WiFi DEVICE_WIFI_CONNECTED = 2, //设备连接WiFi成功 DEVICE_PLATFORM_REGISTED = 3, //设备注册平台成功 DEVICE_ACCOUNT_BINDED = 4 //设备已经绑定帐户第三步添加设备到当前帐号中。调用addDevice:deviceSerial:verifyCode:completion:接口进行设备添加。当状态为DEVICE_PLATFORM_REGISTED时方可添加成功。注意：DEVICE_WIFI_CONNECTED和DEVICE_PLATFORM_REGISTED状态上报可能会丢失，此时可在适当时机查询设备当前的状态，根据设备状态进行后续操作，详见demo中示例代码。重置设备再次添加时，某些设备DEVICE_ACCOUNT_BINDED状态返回出现异常，所以不建议根据DEVICE_ACCOUNT_BINDED判定设备是否已绑定。设备是否已绑定帐户以服务端查到的状态为准。
说明
4.8.3版本中新增配网接口：startConfigWifi:password:deviceSerial:mode:deviceStatus:。该接口通过设置mode参数可使用不同的配网方式，包括原有配网方式和新增的声波配网方式。如果使用声波配网方式，设备端也需支持声波配网功能。支持声波配网的设备见附录。同时该接口支持批量配网，deviceSerial设置为空即可实现批量配网。详见demo。
支持AP配网的设备可使用AP配网模式。根据EZProbeDeviceInfo信息可获知设备支持的配网方式，但由于旧设备在系统中可能查询不到，故也可以采用观察设备指示灯闪烁方式判断设备当前的配网模式。
- 红蓝闪烁为普通的配网方式，蓝灯闪烁为AP配网方式。
AP配网需要将手机连接设备发出的Wi-Fi信号，然后调用EZWiFiConfigManager类中的startAPWifiConfigWithWifiName:wifiPwd:deviceSerial:verifyCode:reuslt:将可连接互联网的Wi-Fi信息发送给设备。设备在接收到Wi-Fi信息后，会关闭AP模式，尝试连接Wi-Fi。
特别说明： 账户下删除设备重新进行wifi配置并且添加时，请在重置设备等待2分钟以后再调用wifi配置的相关接口可以提高wifi配置的成功率，否则会降低成功率，因为重置设备以后我们平台将在2分钟内得到设备下线的状态，只有平台认为下线了，wifi配置成功率才会高。
示例代码：
查询设备状态
[EZOpenSDK probeDeviceInfo:deviceSerial deviceType:deviceType completion:^(EZProbeDeviceInfo * deviceInfo, NSError * error) { if (error) { if (error.code == EZ_HTTPS_DEVICE_ADDED_MYSELF) { //已添加过此设备 } else if (error.code == EZ_HTTPS_DEVICE_ONLINE_IS_ADDED) { //此设备已被别人添加 } else if (error.code == EZ_HTTPS_DEVICE_OFFLINE_NOT_ADDED || error.code == EZ_HTTPS_DEVICE_NOT_EXISTS || error.code == EZ_HTTPS_DEVICE_OFFLINE_IS_ADDED || error.code == EZ_HTTPS_DEVICE_OFFLINE_IS_ADDED_MYSELF) { //设备不在线,需连接网络 if (deviceInfo) { //根据设备能力选择合适的配网方式 deviceInfo.supportWifi == 3; //支持smartConfig配网 deviceInfo.supportSoundWave == 1; //支持声波配网 deviceInfo.supportAP == 2; //支持AP配网 } else { //根据设备闪灯情况选择合适的配网方式 } } else { //查询失败，网络不给力,可进行重试 } } else { //设备已在线，可进行添加 } }];配置设备网络
[EZOpenSDK startConfigWifi:WiFiSsid password:WiFPassword deviceSerial:deviceSerial mode:EZWiFiConfigSmart | EZWiFiConfigWave deviceStatus:^(EZWifiConfigStatus status, NSString * deviceSerial) { if (status == DEVICE_WIFI_CONNECTING) { //设备正在连接WiFi } else if (status == DEVICE_WIFI_CONNECTED) { //设备连接WiFi成功 } else if (status == DEVICE_PLATFORM_REGISTED) { //设备注册平台成功,可进行添加流程 } }];配置设备网络过程中DEVICE_WIFI_CONNECTED和DEVICE_PLATFORM_REGISTED状态上报可能会丢失，此时可在适当时机调用步骤1中的接口，查询设备当前状态，根据设备状态进行后续操作。
AP配网示例代码
[EZOpenSDK startAPConfigWifiWithSsid:self.ssid password:self.password deviceSerial:[GlobalKit shareKit].deviceSerialNo verifyCode:[GlobalKit shareKit].deviceVerifyCode result:^(BOOL ret) { if (ret) { //配置成功 } else { //配置失败 } //停止AP配网 [EZOpenSDK stopAPConfigWifi]; }];全新或重置过的海康设备在添加之前需进行激活，萤石设备则不需激活。激活之前需将设备和手机连入同一个局域网，再使用对应接口进行激活，流程如下：
//初始化模块 [EZHCNetDeviceSDK initSDK]; //局域网搜索设备 [EZHCNetDeviceSDK startLocalSearch:^(EZSADPDeviceInfo * device, NSError * error) { }]; //可根据EZSADPDeviceInfo对象中的actived属性判断设备是否已经激活 //激活设备，此处device为EZSADPDeviceInfo对象，pwd为需设定的设备密码，密码为8-16位的字符 [EZHCNetDeviceSDK activeDeviceWithSerial:device.deviceSerial pwd:pwd];添加设备到当前帐号
[EZOpenSDK addDevice:deviceSerial verifyCode:deviceVerifyCode completion:^(NSError * error) { }];详细使用方法见demo。
附录：
声波配网仅支持以下设备类型及对应最低版本，仅供参考
| 设备型号 | 设备具体 | 版本号 | 声波配置 |
|---|---|---|---|
| C2C | CS-C2C-1B2WFR | V5.1.2 build 180313 | 支持 |
| C6P | CS-C6P-7A3WFR | V5.3.2 build 180117 | 支持 |
| C2HC | CS-C2HC-3B2WFR | V5.2.4 build 180125 | 支持 |
| C3W | CS-C3W-3B1WFR | V5.2.4 build 180131 | 支持 |
| C5S | CS-C5S-1B2WFR | V5.2.4 build 180129 | 支持 |
| C5Si | CS-C5Si-3C2WFR | V5.2.4 build 180307 | 支持 |
| C6H | CS-C6H-3B1WFR | V5.2.4 build 180129 | 支持 |
| C6C | CS-C6C-3B2WFR | V5.2.4 build 180129 | 支持 |
| C6HC | CS-C6HC-3B2WFR | V5.2.4 build 180129 | 支持 |
目前支持AP配网的设备型号如下：
| 国内型号 | 海外型号 |
|---|---|
| CS-C4Wi-3C2WFR | HSFLC1（VOXX定制型号） |
| CS-C4Wi-3C2EFR | HSDB2（VOXX定制型号） |
| CS-C4W-3C2WFR | CS-CV206-C0-3B2WFR-KJDS） |
| CS-C3A-1C2WPMFBR | CS-CV206-C0-1A1WFR-KJDS |
| CS-CV310-A0-3B1WFR-KJDS | |
| CS-CV310-A0-1B2WFR-KJDS | |
| CS-CV246-B0-3B2WFR-KJDS |