Open EZVIZ Platform SDK User Manual (iOS)

• This SDK only contains functions which are debugged on the real mobile phones, excluding the functions debugged by the simulator.
• The demo (iOS) has removed the static library and appKey of Open EZVIZ Platform SDK. Please copy the downloaded SDK library file and header file to the EZOpenSDK folder in the root directory of the demo project. Enter the appKey applied on the official site to run the project.

Overview

This document is used for introducing the APIs' definition and API calling sequence of the Open EZVIZ Platform SDK (iOS).

Download SDK

Glossary

Function

Install SDK

You can install the SDK by installing cocoapods or downloading SDK package.

cocoapods Installation

cocoapods Official Site

1. Add the following content in the Podfile file.

   pod 'EZOpenSDK'
   

2. Proceed

   pod install
   

3. Disable target's Bitcode function.
   Build Settings->Enable Bitcode set to NO
4. Installation completed.

Download to Install

1. Download SDK (https://open.ys7.com/mobile/download.html?type=app) and decompress the packet.

2. Create a new XCode project, and import SDK library (libEZOpenSDK.a) and header (as shown in the following figure).
   

3. Import OpenSSL dependent libraries: libssl.a and libcrypto.a, and related header file (as shown in the figure).
   

4. Import system dependent libraries: libstdc++.6.0.9, CoreMedia, AudioToolbox, VideoToolbox.framework, GLKit.framework, OpenAL.framework, MobileCoreServices, SystemConfiguration, CoreTelephony, AVFoundation.framework, libc++, libiconv.2.4.0, libbz2, and libz (as shown in the figure);

5. Add Other Linker Flags -ObjC
   Case Sensitive
   

6. Disable target's Bitcode function. Build Settings->Enable Bitcode set to NO.
7. Configuration completed.

Permission Settings

Set permissions in info.plist file of the project. Find this file in the file navigation of the Xcode project, and right click Open As-> Source Code, and add the corresponding permission codes.

1. Photos Access Permission: If you want to use the open platform's player for recording and capture, you should set the permission to access phone's photos.

   <key>NSPhotoLibraryUsageDescription</key>
   <string>Require accessing to the phone's photos</string>
   <key>NSPhotoLibraryAddUsageDescription</key>
   <string> Require accessing to the phone's photos</string>
   

2. Microphone Access Permission: If you want to perform two-way audio, you should set the permission to access the phone's microphone. Apply for the microphone's access permission from the iOS system before starting two-way audio, otherwise, the first time’s two-way audio will be exceptional.

   <key>NSMicrophoneUsageDescription</key>
   <string>Require accessing to the phone's microphone</string>
   

3. Phone Camera Access Permission: If you want to scan QR code, you should set the permission to access the phone's camera.

   <key>NSCameraUsageDescription</key>
   <string> Require accessing to the phone's camera</string>
   

Main Flow

Initialization

1. The above figure shows the flow of initializing SDK and login.

2. Login contains two modes: the server gets accessToken and client gets accessToken.

   • Server Mode: The server gets accessToken and sends to the client. The client calls setAccessToken: to login.
   • Client Mode: The client calls API openLoginPage:. If the returned accessToken in block is not null, the login is authorized. In this mode, SDK will manage the accessToken's validity and perform auto-refresh. You can call isLogin to check if you have logged in.

3. After login, you can perform further operations.

   Example Code:

   Initialize SDK

   [EZGlobalSDK initLibWithAppKey:@"Your App Key"];
   

   Login Server Mode:

   [EZGlobalSDK setAccessToken:@"Your accessToken"];
   

   Client Mode:

   [EZGlobalSDK getAreaList:^(NSArray * areaList, NSError * error) {
    EZAreaInfo * areaInfo = areaList[?];//Select area information.
    [EZGlobalSDK openLoginPage:[NSString stringWithFormat:@"%ld",(long)areaInfo.id]
                    completion:^(EZAccessToken * accessToken) {
   
                    }];
   }
   

Live View

Steps:

1. Create a player.Call createPlayerWithDeviceSerial:cameraNo: to create a player.

2. Configure the player.After creating player, you should set proxy, set view, and set its verification code.

3. Start live view. Call startRealPlay to start live view.
   Example Code：

   //Create a player, or you can create by EZPlayer class.
   EZPlayer *player = [EZGlobalSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo];
   
   //Optional but recommended. After configuring player, you can set the proxy.
   player.delegate = self;
   
   //Optional. Required if the device has enabled video/picture encryption, which depends on the isEncrypt of EZDeviceInfo.
   [player setPlayVerifyCode:verifyCode];
   
   //Set view.
   [player setPlayerView:playerView];
   
   //Start live view.
   [player startRealPlay];
   

Notes:

1. Call setVideoLevel:cameraNo:videoLevel:completion: to set the video's definition. You can adjust the definition before or after starting live view. If you set the definition after starting live view, please stop live view by calling stopRealPlay and start again by calling startRealPlay to take effect.
2. If the live view is started, you can receive a message returned by API didReceivedMessageCode:. If starting live view failed, you will receive an error code in didPlayFailed:. If the error code is 400035 (verification code required) or 400036 (verification code mismatched), the developer should ask the user to enter the verification code again, and call setPlayVerifyCode to set the password, and then start live view again.
3. For one device, if you want to enable different functions (live view, playback, or two-way audio), you should create a player for each function, respectively.

Playback

Steps:

1. Create a player.Call createPlayerWithDeviceSerial:cameraNo: to create a player.
2. Configure the player. After creating the player, you should set proxy, set view, and set its verification code.

3. Start playback.Call startPlaybackFromCloud: or startPlaybackFromDevice to start playback.

   Example Code：

   // Create a player, or you can create by EZPlayer class.
   EZPlayer *player = [EZGlobalSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo];
   
   // Optional but recommended. After configuring the player, you can set the proxy.
   player.delegate = self;
   
   // Optional. Required if the device has enabled video/picture encryption, which depends on the isEncrypt of EZDeviceInfo.
   [player setPlayVerifyCode:verifyCode];
   
   //Set view.
   [player setPlayerView:playerView];
   
   // Play back video files stored on the cloud storage. Get the video file (cloudFile) by calling searchRecordFileFromCloud:cameraNo:beginTime:endTime:completion:.
   [player startPlaybackFromCloud:cloudFile];
   
   //Or
   //Play back video files stored on the device. Get the video file (cloudFile) by calling searchRecordFileFromDevice:cameraNo:beginTime:endTime:completion:.
   [player startPlaybackFromDevice:deviceFile];
   

Notes:

1. Get video information before playback. Call searchRecordFileFromCloud:cameraNo:beginTime: endTime:completion: to get the video files stored in cloud storage, and call searchRecordFileFromDevice:cameraNo:beginTime:endTime:completion: to get the video files stored on device.
2. If the playback is stated, you can receive a message returned by API didReceivedMessageCode:. If starting playback failed, you will receive an error code in didPlayFailed:. If the error code is 400035 (verification code required) or 400036 (verification code mismatched), the developer should ask the user to enter the verification code again, and call setPlayVerifyCode to set the password, and then start playback again.

3. For one device, if you want to enable different functions (live view, playback, or two-way audio), you should create a player for each function, respectively.

   Note：When playback ended, it may report an error code (380101) and the player will not report the playback ended message. If this situation happens, you can call the getOSDTime of EZPlayer to get the current time of the video, and then compare this time with the video's end time. If these two time points are close to, the playback will be regarded as ended. If they are not close to, the playback will be regarded as failed. For version 4.8.2 or above, this problem will be processed automatically in SDK.

Two-Way Audio

Steps:

1. Create a player.Call createPlayerWithDeviceSerial:cameraNo: to create a player.
2. Configure the player. After creating player, you should set proxy, set view, and set its verification code.
3. Start playing. Call startVoiceTalk to start two-way audio.
   Example Code:

    // Create a player, or you can create by EZPlayer class.
    EZPlayer  *talkPlayer = [EZGlobalSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo];

    // Optional but recommended. After configuring the player, you can set the proxy.
    talkPlayer.delegate = self;

    // Optional. Required if the device has enabled video/picture encryption, which depends on the isEncrypt of EZDeviceInfo.
    [talkPlayer setPlayVerifyCode:verifyCode];

    //Start two-way audio.
    [talkPlayer startVoiceTalk];

    //Stop two-way audio.
    [talkPlayer stopVoiceTalk];

For half-duplex two-way audio, the default mode is Listen on Phone and Speak on Device. Perform the following operations to switch the listening and speaking mode.

    //Switch to Listen on Device and Speak on Phone
    [talkPlayer audioTalkPressed:YES];

    //Switch to Listen on Phone and Speak on Device
    [talkPlayer audioTalkPressed:NO];

Notes:

1. The two-way audio operations are different according to the device capability. Get the device two-way audio capability from isSupportTalk of EZDeviceInfo. 0: Not Supported. 1: Supports Full-Duplex Two-Way Audio. 3: Supports Half-Duplex Two-Way Audio.
2. For one device, if you want to enable different functions (live view, playback, or two-way audio), you should create a player for each function, respectively.

Add Device

Steps:

1. Search device information . The object obtained after calling API probeDeviceInfo:completion: is EZProbeDeviceInfo. If it returns device information, it indicates searching succeeded. You can add the device.

2. Set device network parameters. . Call startConfigWifi:password:deviceSerial:deviceStatus: for network configuration. startConfigWifi:password:deviceSerial:deviceStatus: should be used with stopConfigWifi. . Get the content of EZWifiConfigStatus via the callback. See the demo for details.

     DEVICE_WIFI_CONNECTING = 1,   //Device connecting to Wi-Fi...
     DEVICE_WIFI_CONNECTED = 2,    //Device connected to Wi-Fi.
     DEVICE_PLATFORM_REGISTED = 3, //Device registered to the platform
     DEVICE_ACCOUNT_BINDED = 4     //Device bound to the account
   

3. Add device to the current account. Call addDevice:deviceSerial:verifyCode:completion: to add device. When the status is DEVICE_PLATFORM_REGISTED, it indicates adding completed. Note: The status report of DEVICE_WIFI_CONNECTED and DEVICE_PLATFORM_REGISTED may be lost. If lost, you need to search the device current status and perform further operations according to the device status. See the demo for details. When adding reset device, an error may occur when returning the status of DEVICE_ACCOUNT_BINDED. As a result, it is not recommended to check if the device is linked to the account by DEVICE_ACCOUNT_BINDED. You can check this status via the server.

   Notes:

   Added a new API for network configuration in version 4.8.3: startConfigWifi:password:deviceSerial:mode:deviceStatus:. In this API, you can set the mode parameter to select different network configuration methods, including normal mode and sound wave mode. If you want to use sound wave to set network, the device should support this function. See the appendix for the devices which support sound wave mode. This API supports batch configuration. Set deviceSerial as null to realize batch configuration.

   Note: During the process of deleting device from the account, configuring the Wi-Fi, and then adding the device, please wait for two minutes after resetting the device and then call the APIs for Wi-Fi configuration, which can increase the success rate (as the platform can get the device offline status in two minutes after resetting the device. If the platform gets the device offline status, the Wi-Fi configuration success rate will be high.)

   Example Code

   1. Search Device Status

[EZGlobalSDK probeDeviceInfo:deviceSerial
               completion:^(EZProbeDeviceInfo * deviceInfo, NSError * error) {
                     if (deviceInfo)
                     {
                         //Device is online and can be added.
                     }
                     else if (error.code == EZ_HTTPS_DEVICE_ADDED_MYSELF)
                     {
                         //The device is already added to the account.
                     }
                     else if (error.code == EZ_HTTPS_DEVICE_ONLINE_IS_ADDED ||
                              error.code == EZ_HTTPS_DEVICE_OFFLINE_IS_ADDED)
                     {
                         //The device is added to other account.
                     }
                     else if (error.code == EZ_HTTPS_DEVICE_OFFLINE_NOT_ADDED ||
                              error.code == EZ_HTTPS_DEVICE_NOT_EXISTS)
                     {
                         //The device is offline. Connect it to the network.
                     }
                     else
                     {
                         //Searching failed. Network exception. Try again.
                     }
                 }];

1. Configure Device Network

 [EZGlobalSDK startConfigWifi:WiFiSsid
                   password:WiFPassword
               deviceSerial:deviceSerial
                       mode:EZWiFiConfigSmart | EZWiFiConfigWave
               deviceStatus:^(EZWifiConfigStatus status, NSString * deviceSerial) {
                   if (status == DEVICE_WIFI_CONNECTING)
                   {
                       // Device connecting to Wi-Fi...
                   }
                   else if (status == DEVICE_WIFI_CONNECTED)
                   {
                       // Device connected to Wi-Fi.
                   }
                   else if (status == DEVICE_PLATFORM_REGISTED)
                   {
                       //Device registered to the platform. Add it to the account.
                   }
               }];

1. During network configuration, the status report of DEVICE_WIFI_CONNECTED and DEVICE_PLATFORM_REGISTED may be lost. If lost, you need to call the API in Step 1 to search the device current status and perform further operations according to the device status. See the demo for details.

2. The inactive Hikvision device (new or reset device) should be activated before adding (activation is not required by EZVIZ device). Before activation, connect the device and the phone to the same LAN, and then activate the device by calling corresponding API

  //Initialize.
  [EZHCNetDeviceSDK initSDK];

  //Search device in LAN.
  [EZHCNetDeviceSDK startLocalSearch:^(EZSADPDeviceInfo * device, NSError * error) {

  }];

  //You can  check if the device is activated according to the attribute value of actived in EZSADPDeviceInfo object.
  //Activate the device. The device is the object of EZSADPDeviceInfo. pwd is the device password which should contain 8 to 16 characters.
  [EZHCNetDeviceSDK activeDeviceWithSerial:device.deviceSerial pwd:pwd];

1. Add device to the current account.

   [EZGlobalSDK addDevice:deviceSerial
             verifyCode:deviceVerifyCode
             completion:^(NSError * error) {

             }];

For details, see the demo.

Appendix:

Only the following devices support network configuration by sound wave.