标准化demo

1. Android标准化Demo说明文档

Android标准化Demo基于OpenSDK组件实现了乐橙云开放平台音视频相关的核心功能。

建议开发者阅读Demo源代码，作为参考或者移植到自己项目中，有助于快速集成。

特别注意：
1、由于Demo是没有后台saas服务的，故Demo是直接在客户端请求开放平台接口来获取数据以及其他的一些操作。
2、建议开发者涉及调用乐橙开放平台OpenApi的地方，采用开发者后台saas服务去调用乐橙开放平台的OpenApi接口，然后再将数据返回给客户端app，整体系统架构搭建采用云云对接。
3、因为调用乐橙云开放平台接口需要使用到开发者账号信息：appId和appSecret，如果开发者将appId和appSecret放在客户端（APP）代码中来实现这个接口，一旦开发者的客户端被其他人反编译，那么就存在appId和appSecret被盗用的风险。

流程如下：

开发者平台接口时序图

2. 功能描述

管理员模式登录——获取accessToken，作为接下来每个Api接口和SDK方法的必传参数
获取设备列表——分别获取开放平台绑定和乐橙App绑定的设备
设备详情——设备解绑、布防设置、设备升级、网络配置等
实时预览——视频播放、语音对讲、抓图、本地录制等
录像回放——录像下载，云录像/设备录像回放、倍速播放等
设备添加功能已封装成单独模块组件，供客户直接使用

用例功能图

3. 技术术语

技术术语	说明
管理员模式	使用在开放平台注册得到的AppId和AppSecret换取accessToken，类似于账号登录的概念
设备列表获取	通过开发者账号自行请求设备列表相关接口，从乐橙云开放平台获取开发者账号下的设备列表清单。
实时预览、本地录制/抓图	实时预览指在客户端（如手机）上获取设备的实时码流，并进行解码&显示的过程；本地录制指在实时预览过程中，将预览流存储为本地视频文件的行为，支持录制为MP4格式；本地抓图指在实时预览过程中，将当前预览画面存储为本地图片的行为，图片为JPG格式。
设备录像回放	在客户端上获取设备里的SD卡存储的录像文件流，并进行解码&显示的过程。
语音对讲	客户端与设备进行对讲通话的过程，目前支持双向语音对讲。
云录像回放	客户端获取设备存储在云端的录像，并进行解码&显示的过程。
动检开关	设备检测到移动时是否产生报警消息和录像的开关。
云台（PTZ）	即通过终端（如App）控制操作设备。
OpenApi	客户端与乐橙平台交互的接口，Restful Api风格。

4. 工程结构描述

从官网上下载到demo源码解压后的目录结构如下图所示：

DeviceAddModule文件夹为设备添加模块
DeviceDetailModule文件夹为设备详情模块
MediaModule文件夹为媒体模块
MessageModule文件夹为消息模块
mobilecommon文件夹为公共模块
PlayBackModule文件夹为录像模块
thrid-zxing文件夹为设备添加模块的依赖模块，主要用于添加设备时相机扫码（读取设备上的二维码并解析）
usermodule文件夹为用户模块
app文件夹为demo源码，依赖于设备添加模块DeviceAddModule

目录结构

5. 管理员账号模拟登录

根据开发者开发应用的场景不同，使用到的乐橙开放平台云视频的能力也会有所不同。

在获取管理员设备列表以及进行设备操作前，需要获取accessToken（管理员token），我们把获取accessToken的过程叫做管理员账号模拟登录过程，获取管理员token之后，直接进入设备列表界面。
Android Demo的源码中已经帮开发者实现了“获取accessToken”接口的代码，具体请见com.mm.android.mobilecommon.openapi.TokenHelper.java类下的getToken方法。

6. 获取设备列表

Demo会展示此帐号下由开放平台绑定的、乐橙App绑定的设备列表，详情请参考实例代码：com.lechange.demo.ui.DeviceListActivity.java中的deviceList方法。

流程如下图所示：

获取设备列表时序图

7. 实时预览页

实时预览页面，主要展示从设备端拉取到的实时视频流，支持横屏和竖屏两种播放样式，还包含对讲、云台、抓图/录制等功能。具体可参见Demo代码中DeviceOnlineMediaPlayActivityNew.java文件。

流程如下图所示：

实时预览时序图

7.1 实时预览和语音对讲

这两个功能均使用SDK中的方法，一些涉及的SDK接口参数解释如下：

设备号：获取设备详细列表时即可获取到相应的设备号

通道号：获取设备详细列表时即可获取到相应的通道号

播放码：获取设备详细列表时即可获取到相应的播放码

码流类型：默认为高清码流0：高清码流 1：标清码流

7.2 云台

调用OpenApi接口实现App控制设备，具体代码请参考DeviceInfoOpenApiManager.java的controlMovePTZ方法

7.3 录像列表

当你购买了云存储套餐之后，就可以查看云录像，涉及的OpenApi请求参考DeviceInfoOpenApiManager.java的getCloudRecords方法

当设备拥有了TF卡之后，就可以查看设备录像，涉及的OpenApi请求参考DeviceInfoOpenApiManager.java的queryLocalRecords方法

7.4 录像封面

Demo会保存退出实时预览页面之前的最后一帧画面，保存在本地数据库和SD卡，做为设备列表页和预览页面的默认图片。具体代码请参考DeviceLocalCacheManager.java和DeviceLocalCacheDatabase.java

8. 设备详情

8.1 设备升级

当设备程序有更新时，可通过OpenApi接口给设备升级，代码请参考DeviceInfoOpenApiManager.java的upgradeDevice方法

8.2 设备重命名

代码请参考DeviceInfoOpenApiManager.java的modifyDeviceName方法

8.3 设备布防设置

代码请参考DeviceInfoOpenApiManager.java的modifyDeviceAlarmStatus方法

8.4 设备网络配置

当设备在线时，可以通过OpenApi查询到的设备当前连接的wifi网络以及设备周边的wifi信息，同时可以给设备其他切换wifi网络。

涉及的请求OpenApi的代码请参考：

DeviceAddOpenApiManager.java的currentDeviceWifi方法

DeviceAddOpenApiManager.java的wifiAround方法

DeviceAddOpenApiManager.java的controlDeviceWifi方法

录像播放

10. 设备添加组件

10.1 使用流程

DeviceAddModule导入到自己的工程中，步骤如下:

Android studio菜单栏选择 File -> New -> Import Module

导入流程001

选择demo工程中DeviceAddModule所在路径，点击finish完成import

导入流程002

导入流程003

在自己工程app目录下的build文件中，示例代码如下：

//高版本Android Stduio
api project(':usermodule')
api project(':MediaModule')
api project(':PlaybackModule')
api project(':MessageModule')
api project(':DeviceDetailmodule')
//或低版本Android Stduio
compile project(':usermodule')
compile project(':MediaModule')
compile project(':PlaybackModule')
compile project(':MessageModule')
compile project(':DeviceDetailmodule')

备注：有的开发者，在完成以上集成步骤之后，编译项目可能会报Manifest merger failed with multiple errors, see logs这个异常，需要在AndroidManifest.xml清单文件中application标签节点下加入 tools:replace="android:allowBackup,android:label,android:supportsRtl"。

若开发者在build.gradle文件中设置的targetSdkVersion >=29 ，需要在AndroidManifest.xml清单文件中application标签节点下加入android:requestLegacyExternalStorage="true"，申请特殊存储权限。

<application
        android:allowBackup="false"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:requestLegacyExternalStorage="true"
        tools:replace="android:allowBackup,android:label,android:supportsRtl"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
  </application>

目前的设备添加模块是以源码的形式给到开发者的，开发者在集成设备添加模块到自己的工程后如需对设备添加相关的代码进行混淆，可在混淆文件中加入涉及的一些jar包的混淆：

#gson
  -keepattributes Signature
  -dontwarn com.google.gson.**
  -keep class sun.misc.Unsafe {*;}
  -keep class com.google.gson.**{*;}

  #eventbus
  -keep class org.greenrobot.eventbus.**{*;}
  -keepclassmembers class **{
      @org.greenrobot.eventbus.Subscribe <methods>;
  }
  -keep enum org.greenrobot.eventbus.ThreadMode {*;}

  #zxing.jar
  -dontwarn com.google.zxing.**
  -keep class com.google.zxing.**{*;}

  #lechangeSDK.jar
  -dontwarn com.lechange.**
  -keep class com.lechange.**{*;}
  -dontwarn com.company.**
  -keep class com.company.**{*;}

  #pulltorefreshlib.jar
  -dontwarn com.lechange.pulltorefreshlistview.**
  -keep class com.lechange.pulltorefreshlistview.**{*;}

  #DHScanner-1.0.7.aar
  -dontwarn com.mm.android.**
  -keep class com.mm.android.**{*;}

  #imageload4dh.jar
  -dontwarn com.nostra13.universalimageloader.**
  -keep class com.nostra13.universalimageloader.**{*;}

10.2 调用示例代码

/**
  * 第一步：初始化设备添加模块
  *
  * 1: 使用设备添加模块，必须先调用该方法完成初始化，此初始化会包含LCOpenSDK_Api类中的setHost()方法，因此不必再次调用setHost()
  * 2: 此方法会抛出异常，假如初始化失败(如获取token失败等)，会在异常中返回具体的Throwable
  */
try {
    CommonParam commonParam = new CommonParam();
    //(必传) 传入开放平台的域名(含端口)，国内一般为：https://openapi.lechange.cn:443，海外一般为：https://openapi.easy4ip.com:443
    commonParam.setEnvirment(CONST.Envirment.CHINA_PRO.url);
    //(必传) Android的Application对象
    commonParam.setContext(EnvGuideActivity.this.getApplication());
    //(必传) 应用Id(乐橙开放平台注册获取)
    commonParam.setAppId("请替换成自己的appId");
    //(必传) 应用Id(乐橙开放平台注册获取)
    commonParam.setAppSecret("请替换成自己的appSecret");
    //(非必传) 用户唯一id，默认appId
    commonParam.setUserId("");
    //开始初始化
    LCDeviceEngine.newInstance().init(commonParam);
} catch (Throwable e) {
}

/**
  * 第二步：开启设备添加流程
  *
  * 1: 此方法会抛出异常（如未初始化等）
  * 2: 此方法需在init初始化成功之后调用
  */
try {
    LCDeviceEngine.newInstance().addDevice(this);
} catch (Exception e) {
}

10.3 注意事项

设备添加模块的AndroidManifest.xml文件中已经默认开启了乐橙SDK所需的所有权限，开发者集成设备添加模块后无需再开启权限，具体权限可参考设备添加模块中的AndroidManifest.xml文件。
设备添加模块中的LCDeviceEngine类中的Init方法中包含了LCOpenSDK_Api.setHost的调用，因此若开发者的项目中使用了设备添加模块，则无需再次调用setHost接口。
设备添加模块目前提供的源码不支持AndroidX，因此若开发者的项目使用的是AndroidX，可通过如下方式将设备添加模块转为AndroidX:
方式一：使用AndroidStudio将Android转为AndroidX，具体操作可自行百度；
方式二：将设备添加模块打包为aar，然后引入到自己的工程中。