开始使用
  • English
  • 简体中文
前往官网
开始使用
  • English
  • 简体中文
前往官网
  • 开始使用
  • 核心概念
  • 开发指南
  • 设备能力与事件参考
  • API 参考
  • SDK 与工具
    • Android SDK
      • Android OpenSDK
      • Android 标准 Demo
    • iOS SDK
    • PC SDK
    • ImouPlayer 轻应用 JavaScript SDK
    • SDK 隐私政策
    • Postman 调试
    • 图片解密
  • 方案
  • 平台与支持
本页目录
1. 安装 OpenSDK
2. 工程配置
2.1 配置 AndroidManifest
2.2 配置 build.gradle
3. 添加设备
3.1 调用 SDK 接口无线添加
3.1.1 SmartConfig 添加
3.1.2 SoftAP 添加
3.2 集成 LCDeviceAddModule
4. OpenSDK 初始化
5. 设置 OpenSDK 日志级别
6. 播放功能
6.1 实时预览
6.2 设备录像回放
6.3 云录像回放
7. 语音对讲
8. 下载功能
8.1 设备录像下载
8.2 云录像下载
9. 设备数据解密

Android OpenSDK

Android OpenSDK 对接文档

本文以 Demo 工程搭建为例(IDE 为 Android Studio,简称 AS),介绍 OpenSDK 对接流程。

Android OpenSDK 资源下载

1. 安装 OpenSDK

  • 下载并解压 Android OpenSDK 压缩包

  • 将 libs/LCOpenSDK.aar 复制到您工程对应目录

添加完成后,AS 工程结构如下:

AS Engineering Structure

2. 工程配置

2.1 配置 AndroidManifest

须在 AndroidManifest.xml 中声明相关权限:

<!-- 基础权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!-- Required permissions for distribution network -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Bluetooth pairing (Android 12+); see [移动端隐私说明](/book/zh/06-sdk/08.privacy.md) -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.VIBRATE" />
<!-- Intercom required permissions -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

说明:请务必配置相关权限,否则可能导致功能异常:未开启录音权限会导致对讲失败;未开启读写存储权限会导致视频下载失败、无线配网无声音、配网失败等;蓝牙配网/配对需 BLUETOOTH_*(见 移动端隐私说明)。

2.2 配置 build.gradle

在 AS 工程 app 模块的 build.gradle 中,可按需选择兼容的 CPU 架构:

android {
 …
 defaultConfig {
 …
 ndk{
 abiFilters "armeabi","arm64-v8a"
 }
 }
}

3. 添加设备

添加设备指先为设备完成配网,再将设备绑定到当前账号。

SDK 目前支持两种配网方式:无线配网与 Soft AP 配网(有线联网一般无需配网)。

无线添加流程较复杂。为便于开发者灵活实现添加设备,提供两种方案:一是直接调用 SDK 接口,由开发者自行实现添加流程;二是集成 Demo 中封装的添加模块,快速对接。

说明:

未绑定设备的添加须知:

  1. 配网前须确认当前设备支持的配网类型,并选择对应配网方式。

  2. 无线设备需通过无线配对传入 Wi-Fi 密码,设备上线后方可添加。

  3. 支持 Soft AP 添加的设备(设备自带热点)须使用 Soft AP 配对。

  4. 有线设备连接网线后可直接查询状态并在线添加(无配网步骤,但网线须能访问外网)。

以下分别说明两种方案的对接流程。

3.1 调用 SDK 接口无线添加

3.1.1 SmartConfig 添加

添加步骤:

  • 扫描设备底部标签或手动输入,获取设备 S/N 等信息。

  • 调用 unBindDeviceInfo API,查询设备支持的配网模式与绑定状态。

  • 判断设备是否已绑定。

  • 判断当前设备是否支持 SmartConfig 配网模式。

  • 调用 deviceAddingProcessGuideInfoGet 获取添加引导页与文案提示(可选)。

  • 启动无线配网,在局域网内搜索设备初始化信息。

  • 搜到设备后停止配网并停止搜索。

  • 初始化设备(无安全码的设备须通过 SDK 初始化)。

  • 检查设备是否在线及当前能力集。

  • 绑定设备。

Device adding process1

3.1.2 SoftAP 添加

添加步骤:

  • 扫描设备底部标签或手动输入,获取设备 S/N 等信息。

  • 调用 unBindDeviceInfo API,查询设备支持的配网模式与绑定状态。

  • 判断设备是否已绑定。

  • 判断当前设备是否支持 SoftAP 配网模式。

  • 调用 deviceAddingProcessGuideInfoGet 获取添加引导页与文案提示(可选)。

  • 连接设备热点。

  • 在局域网搜索设备初始化信息:若已搜到设备信息,可直接绑定。

  • 启动 SoftAP 配网。

  • 检查设备是否在线及当前能力集。

  • 绑定设备。

Device adding process2

3.2 集成 LCDeviceAddModule

添加步骤:

  • 导入设备添加组件,参见 Android 标准 Demo 文档

  • 在布局文件中添加触发添加设备的控件

<TextView
 android:id="@+id/tv_add"
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 android:text="Hello World!"
 app:layout_constraintBottom_toBottomOf="parent"
 app:layout_constraintLeft_toLeftOf="parent"
 app:layout_constraintRight_toRightOf="parent"
 app:layout_constraintTop_toTopOf="parent" />
  • 初始化设备添加模块
try {
 // 初始化参数(海外数据中心与 §4 OpenSDK 初始化 host 保持一致)
 CommonParam commonParam = new CommonParam();
 commonParam.setEnvirment("https://openapi-[DataCenter].easy4ip.com:443");
 commonParam.setContext(MainActivity.this.getApplication());
 commonParam.setAppId("…"); // 开放平台 AppId
 commonParam.setAppSecret("…"); // 开放平台 AppSecret(仅建议放在服务端,Demo 为演示写在客户端)
 LCDeviceEngine.newInstance().init(commonParam);
 } catch (Throwable throwable) {
 throwable.printStackTrace();
 }
 findViewById(R.id.tv_add).setOnClickListener(new View.OnClickListener() {
 @Override
 public void onClick(View v) {
 try {
 LCDeviceEngine.newInstance().addDevice(MainActivity.this);
 } catch (Exception e) {
 e.printStackTrace();
 }
 }
 });

4. OpenSDK 初始化

LCOpenSDK_Api 是 SDK 与开放平台 REST 交互的封装类,应作为首个调用的接口,在调用其他接口前完成初始化与参数设置。

初始化流程如下:

OpenSDK initialize

示例代码如下:

// init LCOpenSDK_Api
String token = ""; // Developer access token
String host = "openapi-[Data Center].easy4ip.com:443";
InitParams initParams = new InitParams(this, host, token);
try {
 int iRet = LCOpenSDK_Api.initOpenApi(initParams);
} catch (Throwable throwable) {
 throwable.printStackTrace();
}

说明:初始化前须先取得 accessToken:管理员 accessToken 或 子账号 accessToken。host 中的 [DataCenter] 替换为实际数据中心标识(与控制台、Open API 请求域名一致)。

5. 设置 OpenSDK 日志级别

  • 调用 LCOpenSDK_Utils.enableLogPrint() 开启或关闭 SDK 内部日志打印

  • 调用 LCOpenSDK_Utils.setLogLevel() 设置日志级别:0 fatal;1 error;2 warning;3 info;4 debug

说明:可调整 SDK 日志级别以便复现问题并抓取日志,便于后续定位与分析。

6. 播放功能

SDK 支持的播放类型主要包括:实时预览、设备录像回放、云录像回放。使用 SDK 播放功能前,须在布局文件中创建播放父窗口:

<!-- Play window container -->
<FrameLayout
 android:id="@+id/live_window"
 android:layout_width="match_parent"
 android:layout_height="200dp">
 <!-- Render content -->
 <FrameLayout
 android:id="@+id/live_window_content"
 android:layout_width="match_parent"
 android:layout_height="match_parent"/>
 </FrameLayout>

说明:SDK 中完成播放功能的类继承自 FrameLayout,因此需要父窗口容器。

初始化播放父窗口,并计算渲染内容 FrameLayout 的高度:

//Initialize the layout
FrameLayout fr_window = findViewById(R.id.live_window);
 FrameLayout getFr_window_content = findViewById(R.id.live_window_content);
//Calculate the height of fr_window in a ratio of 9:16
 LinearLayout.LayoutParams layoutParams = new LinearLayout.LayoutParams(fr_window.getLayoutParams());
 DisplayMetrics metrics = new DisplayMetrics();
 getWindowManager().getDefaultDisplay().getMetrics(metrics);
 layoutParams.width =metrics.widthPixels;//screen width
 layoutParams.height = metrics.heightPixels*9/16;
 layoutParams.setMargins(0, 0, 0, 0);
 fr_window.setLayoutParams(layoutParams);

6.1 实时预览

实时预览主要步骤:

  • 创建布局并初始化(参见上文播放窗口配置)

  • 初始化播放类 LCOpenSDK_PlayRealWindow

  • 为 LCOpenSDK_PlayRealWindow 添加事件监听与手势监听

  • 获取播放参数(开发者 查询设备信息)

  • 开始/停止播放

  • 释放资源

预览流程:

Real-time preview

示例代码:

//Initialize playwindow
LCOpenSDK_PlayRealWindow playWindow= new LCOpenSDK_PlayRealWindow();
playWindow.initPlayWindow(this, (ViewGroup) findViewById(R.id.live_window_content), 0, false);
//The developer implements event monitoring and sets the monitoring to playWindow
LCOpenSDK_EventListener listener = new LCOpenSDK_EventListener(){...}//Developer implements event listener callback
playWindow.setWindowListener(listener);
//Turn on tidy up monitoring
playWindow.openTouchListener();
/**
 * Start preview
 * 1. Prepare to preview the parameters
 * 2. Open preview
 * 3. Process the preview result in the LCOpenSDK_EventListener callback
 * 4. Stop preview
 * 5. Release resources
 */
LCOpenSDK_ParamReal paramReal = new LCOpenSDK_ParamReal()
playWindow.playRtspReal(paramReal);
playWindow.stopRtspReal(true);
playWindow.uninitPlayWindow();

6.2 设备录像回放

设备录像回放主要步骤:

  • 创建布局并初始化(参见上文播放窗口配置)

  • 初始化播放类 LCOpenSDK_PlayBackWindow

  • 为 LCOpenSDK_PlayBackWindow 添加事件监听与手势监听

  • 获取播放参数(开发者 查询设备本地录像)

  • 开始/停止播放

  • 释放资源

回放流程:

Local recording

示例代码:

//Initialize playwindow
LCOpenSDK_PlayBackWindow playWindow= new LCOpenSDK_PlayBackWindow();
playWindow.initPlayWindow(this, (ViewGroup) findViewById(R.id.live_window_content), 0, true);
//The developer implements event monitoring and sets the monitoring to playWindow
LCOpenSDK_EventListener listener = new LCOpenSDK_EventListener(){...}//Developer implements event listener callback
playWindow.setWindowListener(listener);
//Turn on tidy up monitoring
playWindow.openTouchListener();
/**
 * Start playback
 * 1. Ready to playback parameters
 * 2. Turn on playback
 * 3. Process the playback result in the LCOpenSDK_EventListener callback
 * 4. Stop playback
 * 5. Release resources
 */
LCOpenSDK_ParamDeviceRecord paramDeviceRecord = new LCOpenSDK_ParamDeviceRecord(...);//Developers get it from the video list
playWindow.playRtspPlayback(paramDeviceRecord);
playWindow.stopRtspPlayback(true);
playWindow.uninitPlayWindow();

6.3 云录像回放

云录像回放主要步骤:

  • 创建布局并初始化(参见上文播放窗口配置)

  • 初始化播放类 LCOpenSDK_PlayBackWindow

  • 为 LCOpenSDK_PlayBackWindow 添加事件监听与手势监听

  • 获取播放参数(开发者 查询设备云录像)

  • 开始/停止播放

  • 释放资源

云录像回放流程:

Cloud video

示例代码:

//Initialize playwindow
LCOpenSDK_PlayBackWindow playWindow = new LCOpenSDK_PlayBackWindow();
playWindow.initPlayWindow(this, (ViewGroup) findViewById(R.id.live_window_content), 0, true);
//The developer implements event monitoring and sets the monitoring to playWindow
LCOpenSDK_EventListener listener = new LCOpenSDK_EventListener(){...}//Developer implements event listener callback
playWindow.setWindowListener(listener);
//Turn on tidy up monitoring
playWindow.openTouchListener();
/**
 * Start playback
 * 1. Ready to playback parameters
 * 2. Turn on playback
 * 3. Process the playback result in the LCOpenSDK_EventListener callback
 * 4. Stop playback
 * 5. Release resources
 */
LCOpenSDK_ParamCloudRecord paramCloudRecord = new LCOpenSDK_ParamCloudRecord(...)//The developer gets it from the cloud recording list
playWindow.playCloud(paramCloudRecord);
playWindow.stopCloud(true);
playWindow.uninitPlayWindow();

说明:

  1. 播放窗口监听回调类非常重要,是上层与底层直接交互的回调类。
  2. LCOpenSDK_EventListener 类说明请参阅 OpenSDK 接口文档。

7. 语音对讲

OpenSDK 当前须在预览成功开启后才能对讲。对讲主要步骤:

  • 获取对讲参数

  • 判断当前设备是否具备对讲能力(设备能力集包含 AudioTalk 或 AudioTalkV1;可先通过 设备查询 获取 ability)

  • 设置对讲监听

  • 开始对讲

  • 停止对讲

对讲流程:

Voice intercom

示例代码:

//Turn off the preview sound
playWindow.stopAudio();
//Set up intercom monitoring
LCOpenSDK_Talk.setListener(new LCOpenSDK_TalkerListener());
//Prepare the intercom parameters (the developer obtains the device information currently being previewed)
LCOpenSDK_ParamTalk paramTalk = new LCOpenSDK_ParamTalk(...);
//Start intercom
LCOpenSDK_Talk.playTalk(paramTalk);
//Stop intercom
LCOpenSDK_Talk.stopTalk();
//Release the intercom monitor
LCOpenSDK_Talk.setListener(null);
//Turn on the preview sound
playWindow.playAudio();

8. 下载功能

SDK 支持设备 SD 卡录像下载与云录像下载。以下分别说明两种下载流程。

8.1 设备录像下载

设备录像下载主要步骤:

  • 获取设备录像列表

  • 初始化设备录像下载参数

  • 设置下载监听

  • 开始下载

设备录像下载流程:

Device video download

示例代码:

//Get device recording list (developer requests to get it)
// queryLocalRecords — 见 [本地录像查询](/book/zh/05-api/90.old/device/record/local/summary.html)
//Set up download listener (the developer overrides the LCOpenSDK_DownloadListener class method)
LCOpenSDK_Download.setListener(new LCOpenSDK_DownloadListener());
//Start downloading (the developer is ready to download parameters)
LCOpenSDK_Download.startDownload(...);

8.2 云录像下载

云录像下载主要步骤:

  • 获取云录像列表

  • 初始化云录像下载参数

  • 设置下载监听

  • 开始下载

云录像下载流程:

Cloud video download 示例代码:

//Get cloud recording list (developer requests to get it)
// queryCloudRecords — 见 [云录像查询](/book/zh/05-api/11.cloud/summary.html)
//Set up download listener (the developer overrides the LCOpenSDK_DownloadListener class method)
LCOpenSDK_Download.setListener(new LCOpenSDK_DownloadListener());
//Start downloading (the developer is ready to download parameters)
 LCOpenSDK_Download.startDownload(...);

9. 设备数据解密

目前设备告警缩略图与录像封面图默认加密存储,须解密后方可正常显示:使用 LCOpenSDK_Utils.decryptPic 解密图片数据(密钥规则与设备加密模式、deviceId 相关,与预览 psk 用法一致)。

byte[] dataOut = null;
int ret = LCOpenSDK_Utils.decryptPic(encryptedBytes, deviceId, decryptKey, dataOut);
// ret == 0 时 dataOut 为可展示的 JPEG/PNG 字节流,可交给 Bitmap 或图片控件

告警与录像接口返回的 URL 或二进制流若为加密格式,须在展示前调用上述接口;详见 告警消息 与各录像查询 API 的字段说明。

queryLocalRecords(分页查询设备本地录像片段)
Android 标准 Demo