Open EZVIZ Platform SDKUser Manual (Android)

• Ezviz Studio Admin
• Ezviz Studio Setup

This Video Explain How To Playback Ezviz Device On Ezviz Studio PC SoftwareRelated Tutorials: Tutorials: https://bit.ly/3. EZVIZ PC Studio Software. Windows PC Software. Upgrade Pack for S2 Action Camera. Upgrade Pack for S5 Plus Action Camera. Upgrade Pack for S6 Action Camera. Upgrade Pack for S1C Action Camera. Video Plugin for Windows. User Manual LC3. T2 - Open/Close Detector. UV-C Air Purifier.

Overview

Thisdocument introduces the APIs' definition and calling sequence of Open EZVIZPlatform SDK (Android).

Glossary

Functions

Project Configuration

EnvironmentSupports Android Studio 1.4 and aboveSupports JDK 7.0 and aboveSupports Android system version 4.0 and above

1. Apply for appKey

Firstly,you should apply to us about developer appkey.

2. Install SDK

SDKInstallation Steps

Get SDK via Gradle

Ifyou have installed by directly downloading in the previous, you should deletethe previously copied.so library file and .jar packet.

dependencies {

compile 'com.hikvision.ezviz:ezviz-sdk:4.8.6.2'

}

Get SDK via Repository inMaven

Ifyou have installed by directly downloading in the previous, you should deletethe previously copied.so library file and .jar packet.

<dependency>

<groupId>com.hikvision.ezviz</groupId>

<artifactId>ezviz-sdk</artifactId>

<version>4.8.6.2</version>

</dependency>

Directly Download

1.Copythe .so file in the directory of /libs/armeabi-v7a to the correspondingdirectory of your own project.2.Copy the .jar package in the directory of /libs to the correspondingdirectory of your own project (including .jmdns and .gson).

3. Configure Project

Configure AndroidPermission

Addin the file AndroidMainfest.xml:

//Network Permission

<uses-permission android:name='android.permission.INTERNET'/>

<uses-permission android:name='android.permission.ACCESS_NETWORK_STATE'/>

<uses-permission android:name='android.permission.RECORD_AUDIO'/>

<uses-permission android:name='android.permission.READ_PHONE_STATE'/>

//Storage Permission

<uses-permission android:name='android.permission.WRITE_EXTERNAL_STORAGE'/>

//Wi-Fi Status Permission

<uses-permission android:name='android.permission.ACCESS_WIFI_STATE'/>

<uses-permission android:name='android.permission.CHANGE_WIFI_STATE'/>

<uses-permission android:name='android.permission.CHANGE_WIFI_MULTICAST_STATE'/>

Configure build.gradle

defaultConfig {

...

ndk {

abiFilters 'armeabi-v7a'//Only supports v7a

}

}

sourceSets {

main {

jniLibs.srcDirs = ['libs']

}

}

Note: Currently onlysupports v7a. It can only be used in armeabi-v7a.

ndk{

abiFilters 'armeabi-v7a'//Only supports 32-bit.

}

Forpermission android.permission.READ_PHONE_STATE, you are not required to add itif not necessary.

ConfigureAndroidManifest.xml

Addthe activity definition as follows, including login, enabling cloud storage,etc.

<activity

android:name='com.videogo.main.EzvizWebViewActivity'

android:screenOrientation='portrait'

android:configChanges='orientation|keyboardHidden'>

</activity>

Addthe following broadcast receiver, which is used for receiving the networkchanges to refresh the SDK network status, for receiving the login succeededmessage to enable other pages. Replace ##you_BroadcastReceiver as the broadcastreceiver you defined in the code.

<receiver

android:name='you_BroadcastReceiver'

android:exported='false' >

<intent-filter>

<action android:name='com.videogo.action.OAUTH_SUCCESS_ACTION'/>

</intent-filter>

</receiver>

4. Initialize Code

Itis recommended to initialize the code in the application.

/** * Enable/Disable SDK logs. */

EZGlobalSDK.showSDKLog(true);

/** * Supports P2P streaming or not. See theAPI for details. */

EZGlobalSDK.enableP2P(false);

/** * Replace the APP_KEY as the one youapplied. */

EZGlobalSDK.initLib(this,APP_KEY);

5. Code Obfuscation

Add the following contentwhen packaging.

-dontwarn com.ezviz.**

-keep class com.ezviz.** { *;}

-dontwarn com.hik.**

-keep class com.hik.** { *;}

-dontwarn com.hikvision.**

-keep class com.hikvision.** { *;}

-dontwarn com.videogo.**

-keep class com.videogo.** { *;}

-dontwarn org.MediaPlayer.PlayM4.**

-keep class org.MediaPlayer.PlayM4.** { *;}

-dontwarn com.sun.jna.**

-keep class com.sun.jna.**{*;}

# Gson Obfuscation

-keepattributes Annotation

-keep class sun.misc.Unsafe { *; }

-keep class com.idea.fifaalarmclock.entity.*

-keep class com.google.gson.stream.* { *; }

#xlog Obfuscation of mars

-keep class com.tencent.mars.** {

publicprotected private *;

}

SDK Initialization

1. InitializeAuthorization Process

For Authorized User:

Oversea:

1. The third-party servergets accessToken and expiry time via server API. accessToken is used forauthorization, expiry time is used for scheduled refresh.

2. The third-party serversends the accessToken to the third-party application (integrated with SDK). Thethird-party application calls setAccessToken (String accesstoken) to finishauthorization.

3. EZGlobalSDK.getInstance().setAccessToken(StringaccessToken);

4. Call after logoutLogout

5. EZGlobalSDK.getInstance().logout();

Or

EZGlobalSDK.getInstance().setAccessToken(null);

For the users who wantsto call the SDK login page for authorization:

1. Get area list by callingEZGlobalSDK.getInstance().getAreaList(). Select the current area's areaId andenter the login H5 page by calling EZGlobalSDK.getInstance().openLoginPage(StringareaId). You can log in to the account in this page.

2. EZGlobalSDK.getInstance().getAreaList();

3.

4. EZGlobalSDK.getInstance().openLoginPage(StringareaId)

5. After login, it will sendbroadcast. If the action is Constant.OAUTH_SUCCESS_ACTION, it indicates loginsucceeded. After login, you can perform further operation in the App and callthe EZGlobalSDK API, and the EZGlobalSDK will automatically complete the configurationof accessToken authorization.

6. The EZGlobalSDK can cachethe accessToken. When you open the App next time, the authorization will becompleted during initialization.

7. If you the accessToken isauthenticated via H5 page, EZGlobalSDK can refresh the accessTokenautomatically, and it will not be expired or invalid.

8. To get the accessTokencached by EZGlobalSDK, call EZGlobalSDK.getInstance().getEZAccessToken() andyou will get EZAccessToken, which includes accessToken and its expiry time. Youshould consider accessToken's expiry time if you call the EZVIZ API byaccessToken.

9. EZGlobalSDK.getInstance().getEZAccessToke();

2. Live View

1. Steps:

1. Create player

Ezviz Studio Admin

2. Set handle callback anddisplay area. If the device is configured with stream encryption, you shouldset the encryption key (by default, key is the device's 6-bit verificationcode)

3. Start live view

4. Stop live view

5. Release the player

ExampleCode:

EZPlayerplayer =EZGlobalSDK.getInstance().createPlayer(String deviceSerial,intcameraNo);

//Seta handle for transmitting message from player to handle.

player.setHandler(mHandler);

//Setthe display parameter of the player

player.setSurfaceHold(mHolder);

/**

*For the device whose stream is encrypted, the encryption key is required.

*The stream encryption key is used for decrypting the encrypted video. This APIcan be called when receiving error callback of ERROR_INNER_VERIFYCODE_NEED orERROR_INNER_VERIFYCODE_ERROR.

* @paramverifyCode Stream encryption key (by default, key is the device's 6-bitverification code).

*/

player.setPlayVerifyCode(String verifyCode);

//Startlive view

player.startRealPlay();

//Stoplive view

player.stopRealPlay();

//Releaseresource

player.release();

2. Notes:

1. During live view, you canperform the following operations: recording, capture, image flipping, two-wayaudio, PTZ control, audio control, and digital zoom. For details, refer toEZPlayer of API. The APIs which control the PTZ, lens, and two-way audio are restrictedAPIs. You should call them based on the device capability. For the devicecapability, refer to the attribute value of EZDeviceInfo.

//StartRecording. recordFile:The local saving path of the recorded video files. Forexample: Environment.getExternalStorageDirectory().getPath()+'/abc'

player.startLocalRecordWithFile(String recordFile)

//Stop Recording. It is used with startLocalRecordWithFile.

player.stopLocalRecord()

//Capture

player.capturePicture()

//ImageFlipping

EZGlobalSDK.getInstance().controlVideoFlip(deviceSerial,cameraNo,EZConstants.EZPTZDisplayCommand.EZPTZDisplayCommandFlip)

//AudioControl

player.openSound();

player.closeSound();

/**

* APIfor PTZ Control

* TheAPI is long-running. Call it in the thread.

* @paramdeviceSerial Device Serial No.

* @paramcameraNo Channel No.

* @paramcommand PTZ Control Command

* @paramaction Start/Stop

* @paramspeed Speed level (0 to 2)

* @returnreturn Operation succeeded or failed (returning with error code)

*/

EZGlobalSDK.getInstance().controlPTZ(String deviceSerial,intcameraNo, EZPTZCommand command, EZPTZAction action, intspeed)

1. Set the video's definition(videoLevel) by setVideoLevel of EZGlobalSDK. Adjust it before or during liveview. During live view, if you set the video definition, stop live view(stopRealPlay) first and then start live view again (startRealPlay) so that thesettings will take effect.

2. EZGlobalSDK.getInstance().setVideoLevel(StringdeviceSerial,int cameraNo, intvideoLevel);

3.

4. //Configured

5. // Stop live view

6. stopRealPlay();

7. // Start Live View

8. startRealPlay();

9. After starting live view,you will receive the following messages in the callback message.

a.Succeeded Message: 102 （EZRealPlayConstants.MSG_REALPLAY_PLAY_SUCCESS）.b. Succeeded Message: 134 （EZConstants.MSG_VIDEO_SIZE_CHANGED）.c. Failed Message: 103 （EZRealPlayConstants.MSG_REALPLAY_PLAY_FAIL）. Check error code (errorCode) if failed.If the error code is 400035 (verification code required) or 400036(verification code error), the developer should ask the user to enter theverification code again, and call setPlayVerifyCode to set the password, andthen start live view again.

@Override

public void handleMessage(Messagemsg) {

switch(msg.what) {

caseEZConstants.EZRealPlayConstants.MSG_REALPLAY_PLAY_SUCCESS:

//Playing succeeded.

break;

caseEZConstants.EZRealPlayConstants.MSG_REALPLAY_PLAY_FAIL:

//Playing failed with error information.

ErrorInfo errorinfo = (ErrorInfo) msg.obj;

//Returned with error code for playing failed.

intcode = errorinfo.errorCode

// Returned with error code for playing failed module.

String codeStr = errorinfo.moduleCode

//Returned with description for playing failed.

String description = errorinfo.description

//Returned with resolution for playing failed.

String description = errorinfo.sulution

break;

caseEZConstants.MSG_VIDEO_SIZE_CHANGED:

// Parsed image resolution and callback

try {

String temp = (String) msg.obj;

String[] strings = temp.split(':');

int mVideoWidth = Integer.parseInt(strings[0]);

int mVideoHeight = Integer.parseInt(strings[1]);

//Parsed image resolution

} catch (Exception e) {

e.printStackTrace();

}

break;

default:

break;

}

}

3. Playback

1. Steps

1. Create player.

2. Set handle callback anddisplay area. If the device is configured with stream encryption, you shouldset the encryption key (by default, key is the device's 6-bit verificationcode).

3. Start playback.

4. Stop playback.

5. Release player.

ExampleCode:

EZPlayer player =EZGlobalSDK.getInstance().createPlayer(String deviceSerial,intcameraNo);

//Set a handle, which is used for transmitting message from player to handle

player.setHandler(mHandler);

//Setthe display parameter of the player

player.setSurfaceHold(mHolder);

/**

* Forthe device whose stream is encrypted, the encryption key is required.

* Thestream encryption key is used for decrypting the encrypted video. This API canbe called after receiving error callback of ERROR_INNER_VERIFYCODE_NEED orERROR_INNER_VERIFYCODE_ERROR.

* @paramverifyCode Stream encryption key (by default, the key is the device's 6-bitverification code).

*/

player.setPlayVerifyCode(String verifyCode);

/**

*Start Playback (Stored in Cloud Storage)

* @paramcloudFile Video files stored in Cloud Storage. See Search Video Files in CloudStorage below.

* @return true-success, false-failure

*/

player.startPlayback(EZCloudRecordFile cloudFile)

//Or

/**

*Start Playback (Stored in SD Card)

Ezviz Studio Setup

* @paramdeviceFile Video files stored in SD card. See Search Video Files in SD Cardbelow.

* @return true-success, false-failure

*/

player.startPlayback(EZDeviceRecordFile deviceFile)

//Or

/**

*Start Playback (Stored in SD Card) By Time

* @paramstartTime Start time

* @paramstopTime End time

* @return true-success, false-failure

*/

player.startPlayback(Calendar startTime, Calendar stopTime)

/**

* Stop Playback

*/

player.stopPlayback()

2. Notes:

1. Search Video Files inCloud Storage

/**

*Search Video Files in Cloud Storage

*The API contains network operation. Call it in the thread.

* @paramdeviceSerial Device serial No.

* @paramcameraNo Camera No.(EZCameraInfo.cameraNo)

* @paramstartTime Start time of search

* @paramendTime End time of search

* @returnVideo file list in cloud storage

* @throwsBaseException

*/

EZGlobalSDK.getInstance().searchRecordFileFromCloud(String deviceSerial,int cameraNo, Calendar startTime, CalendarendTime)

1. Search Video Files in SDCard

/**

*Search Video Files in SD Card

*If the device is linked with an NVR, it will search the video files stored inthe NVR instead of searching in the device SD card.

*The API is long-running. Call it in the thread.

*/

EZGlobalSDK.getInstance().searchRecordFileFromDevice(StringdeviceSerial, int cameraNo, Calendar startTime,Calendar endTime)

1. During playback, you canperform the following operations: clipping, capture, audio control, digitalzoom, and timeline control (seekPlayback). For details, refer to EZPlayer ofAPI.

/**

* Playback Based on Offset Time

* Call this API when dragging the progressbar. Stop playback first and set the offset time as the start time to startplayback.

* Replace this API with stopPlayback +startPlayback (offsetTime, stopTime)

* @param offsetTime Recording Offset Time

*/

player.seekPlayback(Calendar offsetTime)

1. getOSDTime: Get thecurrent time in the video for playback. If the start time is 8:00, end time is9:00, getOSDTime is 8:30, then the playing progress is 50%.

2. During playback, callpausePlayback to pause playback and call resumePlayback to resume playback.

/**

* PausePlayback

*/

player.pausePlayback()

/**

* Resume Playback

*/

player.resumePlayback()

1. After starting playback,you will receive the following messages in the callback message.

a.SucceededMessage:205(EZConstants.EZPlaybackConstants.MSG_REMOTEPLAYBACK_PLAY_SUCCUSS）.b. Failed Message: 206 (EZConstants.EZPlaybackConstants.MSG_REMOTEPLAYBACK_PLAY_FAIL).Check error code (errorCode) if failed. If the error code is 400035(verification code required) or 400036 (verification code error), the developershould ask the user to enter the verification code again, and callsetPlayVerifyCode to set the password, and then start playback again.c. Video Resolution Callback: 134 (EZConstants.MSG_VIDEO_SIZE_CHANGED)

4. Two-Way Audio

1. Steps:

1. Create two-way audioplayer

2. Set handle callback anddisplay area. If the device is configured with stream encryption, you shouldset the encryption key (by default, key is the device's 6-bit verificationcode)..

3. Start two-way audio.

4. Stop two-way audio.

5. Release two-way audioplayer.

ExampleCode

EZPlayer talk =EZOpenSDK.getInstance().createPlayer(String deviceSerial,intcameraNo);

//Set a handle, which is used for transmitting message from player to handle.

talk.setHandler(mHandler);

/**

*For the device whose stream is encrypted, the encryption key is required.

*The stream encryption key is used for decrypting the encrypted video. This APIcan be called when receiving error callback of ERROR_INNER_VERIFYCODE_NEED orERROR_INNER_VERIFYCODE_ERROR.

* @paramverifyCode Stream encryption key (by default, the key is the device's 6-bitverification code).

*/

talk.setPlayVerifyCode(String verifyCode);

//StartTwo-Way Audio

talk.startVoiceTalk();

//StopTwo-Way Audio

talk.stopVoiceTalk();

//Forhalf-duplex two-way audio, you should call the above API to start two-wayaudio.

//Afterstarting two-way audio, you can perform the following operations(setVoiceTalkStatus) to hear sound from the device or phone.

//Listenon Device and Speak on Phone

talk.setVoiceTalkStatus(true);

//Listen on Phone and Speak on Device

talk.setVoiceTalkStatus(false);

2. Notes:

1. The two-way audiooperations are different according to the device capability. Get the devicetwo-way audio capability by isSupportTalk in EZDeviceInfo. 0: Not Supported. 1:Supports Full-Duplex Two-Way Audio. 3: Supports Half-Duplex Two-Way Audio. Forone device, if you want to enable different functions (live view, playback, ortwo-way audio), you should create a player for each function, respectively.

2. If the video containssound, you should mute the video sound (closeSound) before starting two-wayaudio. After stopping two-way audio, turn on the video sound (openSound). Fordetails, see the demo.

3. After starting two-wayaudio, you will receive the following messages in the callback message.

a.Succeeded Message: 113 （RealPlayMsg.MSG_REALPLAY_VOICETALK_SUCCESS）.b. Failed Message: 114 （RealPlayMsg.MSG_REALPLAY_VOICETALK_FAIL）. Check error code (errorCode) if failed.If the error code is 400035 (verification code required) or 400036(verification code error), the developer should ask the user to enter theverification code again, and call setPlayVerifyCode to set the password, andthen start two-way audio again.

5. Add Device

1. The object aftersearching the device information (API is probeDeviceInfo) is EZProbeDeviceInfo.If it returns device information object, it indicates searching succeeded. Youcan add the device.

try {

EZProbeDeviceInfo mEZProbeDeviceInfo = EZGlobalSDK.getInstance().probeDeviceInfo(StringdeviceSerial);

//Searching completed. Call the API to add device

} catch (BaseException e) {

e.printStackTrace();

//Searching failed.

int code = e.getErrorCode();

//Code Value

120020 Device is online and is addedby the current account (withprompt)

120022 Device is online and is added by other account (withprompt).

120023 Device is offline and is not added by any accounts (callAPI for Wi-Fi settings)

120002 Device does not exist and is not added by any accounts (callAPI for Wi-Fi settings)

120024 Device is offline and is added by other account (withprompt).

120029 Device is offline and isadded by the current account (withprompt).

Other (with prompt)

}

1. Searching completed. Addthe device.

// Searching completed. Add the device.

//deviceSerial: Device serial No.；

//mVerifyCode Device verification code which is on the devicelabel and contains 6 uppercase letters.

try {

boolean ret =EZGlobalSDK.getInstance().addDevice(String deviceSerial, String mVerifyCode);

if (ret) {

//Added.

}

} catch(BaseException e) {

e.printStackTrace();

}

1. Call API for Wi-Fisettings. The startConfigWifi should be used with stopConfigWifi. Afterstarting Wi-Fi configuration, you can define a timer to call stopConfigWiFi tostop the configuration. If you want to use sound wave to set Wi-Fi, thedevice should also support this function. This API supports batchconfiguration. Set deviceSerial as “null” to realize batch configuration.

/**

* StartWi-Fi Settings

* @paramcontext Apply activity context

* @paramdeviceSerial Configure device serialNo.

* @paramssid Wi-Fi SSID

* @parampassword Wi-Fi password

* @paramback Configure Callback

*/

EZGlobalSDK.getInstance().startConfigWifi(Context context,StringdeviceSerial, String ssid, String password,EZOpenSDKListener.EZStartConfigWifiCallback back);

/**

*Start Wi-Fi Settings

* @since4.8.3

* @paramcontext Apply activity context

* @paramdeviceSerial Configure device serialNo.

* @paramssid Wi-Fi SSID

* @parampassword Wi-Fi password

* @parammode Configuration mode. Combine themodes listed in EZWiFiConfigMode (EZWiFiConfigMode.EZWiFiConfigSmart-NormalMode. EZWiFiConfigMode.EZWiFiConfigWave-Sound Wave Mode). E.g.,EZWiFiConfigMode.EZWiFiConfigSmart|EZWiFiConfigMode.EZWiFiConfigWave

* @paramback Configure Callback

*/

EZGlobalSDK.getInstance().startConfigWifi(Context context,StringdeviceSerial, String ssid, String password, intmode,EZOpenSDKListener.EZStartConfigWifiCallback back)；

/**

*Stop Wi-Fi Settings

*/

EZGlobalSDK.getInstance().stopConfigWiFi();

/**

*Configure Callback

*/

EZOpenSDKListener.EZStartConfigWifiCallback mEZStartConfigWifiCallback =

newEZOpenSDKListener.EZStartConfigWifiCallback() {

@Override

public void onStartConfigWifiCallback(StringdeviceSerial，finalEZConstants.EZWifiConfigStatus status) {

AutoWifiConnectingActivity.this.runOnUiThread(newRunnable() {

@Override

public void run() {

if(status EZConstants.EZWifiConfigStatus.DEVICE_WIFI_CONNECTED) {

//Device connected to Wi-Fi.

} else if(status EZConstants.EZWifiConfigStatus.DEVICE_PLATFORM_REGISTED) {

// Device registered to theplatform. Call the adding device API to add it.

}

}

});

}

};

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 thedevice and then call the APIs for Wi-Fi configuration, which can increase thesuccess rate (as the platform can get the device offline status in two minutesafter resetting the device. If the platform gets the device offline status, theWi-Fi configuration success rate will be high.)

Note1: Thestatus reported by DEVICE_WIFI_CONNECTED and DEVICE_PLATFORM_REGISTED may belost. If lost, search the device status by calling probeDeviceInfo and performfurther operations according to the device status.

Note2: For Hikvision device, you may need to activate it before adding it. Searchthe device in LAN and check if the device is activated (activation is notrequired for EZVIZ device). If it is inactive, call the API to activate it.

//sadp Search Device in LAN

EZHCNetDeviceSDK.getInstance().startLocalSearch(newEZHCNetDeviceSDK.SadpDeviceFoundListener() {

@Override

public void onDeviceFound(finalEZSADPDeviceInfo sadp_device_info) {

LogUtil.d(TAG,

'onDeviceFound ' +sadp_device_info.getDeviceSerial() + ' ' +sadp_device_info.getDeviceSerial());

//Findthe device.

//Checkif the device is activated.

booleanisActivied = sadp_device_info.isActived();

}

});

//sadp Disable Searching Device in LAN

EZHCNetDeviceSDK.getInstance().stopLocalSearch();

//sadp Activate Device in LAN

new Thread(newRunnable() {

@Override

public void run() {

final int result= EZHCNetDeviceSDK.getInstance().activeDeviceWithSerial(deviceSerial,mPassword);

if (result 1){

//TODO: 2017/8/15 Activation successful

return;

}else {

//TODO: 2017/8/15 Activationfailed

runOnUiThread(newRunnable() {

@Override

public void run() {

if(result 2020){

//TODO: 2017/8/16 Weak password.

}else{

//TODO: 2017/8/16 Activating failed.

}

}

});

}

}

}).start();

c