智能终端开放接口

一、更改历史

迭代时间	迭代内容
2022.08.26	base_open.aar 1.0.0-1版本
2022.8.29	修改此文档： 1.部分接口描述修改 2.detectFace接口增加参数，单人识别或多人识别
2022.10.27	base_open_1.0.1_2.aar库更新 changelist： 1.新增appkey授权
2022.11.18	base_open_1.0.2_3.aar库更新 changelist： 1.新增sdk保存log入口
2025.01.16	新增行业智能终端开放

二、系统拓扑

前提条件（必读）

使用业务接口前，需先区分设备所使用环境，钉钉和行业在部分参数调用存在差异，可以包对应的文档为准：
【钉钉终端应用】设备激活方式使用手机钉钉扫码设备上的二维码（手机扫设备蓝牙激活）
【行业终端应用】设备激活方式使用手机扫码生成配置二维码后出示给设备（设备扫手机二维码激活）

三、钉钉终端应用接入指南

3.1、接入流程

1.环境搭建

第三方应用开发者拿到魔点开放sdk后，需要把aar文件置于libs目录下，通过gradle加载开放sdk

2.启动配置

调用开放sdk前需要在AndroidManifest.xml文件中配置启动界面的action，魔点应用会在每次启动后判断第三方应用是否存在，如果存在则会拉起第三方应用

<activity android:name=".MainActivity"
        android:exported="true"
        android:launchMode="singleTask">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
        <intent-filter>
            <action android:name="com.moredian.open.start" />
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
</activity>

3.sdk初始化

调用魔点开放open sdk之前，需要通过MdOpenServer初始化sdk,appKey通过魔点开放平台申请；
钉钉终端应用和行业终端应用初始化SDK有些许差异，具体可咨询终端应用对接群；

private void initOpenServer() {
        MdOpenServer.getInstance().init(this,this);
        MdOpenServer.getInstance().register(appKey);
}

4.数据监听

初始化成功后再去注册数据回流监听

@Override
    public void onInitCallBack(boolean isSuccess, String message) {
        Log.d(TAG, "onInitCallBack: isSuccess="+isSuccess+",message="+message);
        isInitSuccess = isSuccess;
        if (isSuccess){
            mOpenListener = new OpenListener();
            MdOpenServer.getInstance().registerListener(mOpenListener);
            getDeviceMode();
            getDeviceBaseInfo();
        }else {
            if (mOpenListener != null){
                MdOpenServer.getInstance().unRegisterListener(mOpenListener);
            }
        }
    }

5.sdk注销

应用或者界面销毁，初始化回调失败，需要通过unRegisterListener注销历史的回流监听，否则下次再次注册，会返回多条相同的数据

3.2、业务接口

名词解释

数据回流类OpenInitListener

private class OpenListener extends IOpenListener.Stub {
        @Override
        public void dataCallBack(String action, String result) throws RemoteException

回调方法	参数	类型	描述
dataCallBack	action	String	发起调用open sdk的动作
dataCallBack	result	String	json格式回调

1.sdk初始化

/**
     * sdk初始化
     * @param context 系统上下文
     * @param openInitListener 初始化回调
     */
    @Override
    public void init(@NonNull Context context, OpenInitListener openInitListener)

方法名	参数	类型	是否必填	描述
init	context	Context	是	上下文
init	openInitListener	OpenInitListener	是	初始化回调

2.sdk注册

/**
     * sdk注册
     */
    @Override
    public void register()

3.sdk注销

应用销毁后应及时注销sdk，注销后，sdk会断开连接，同时释放持有的资源

/**
     * sdk注销
     */
    @Override
    public void release()

4.注册数据回流监听

/**
* 注册数据回流
* @param listener
*/
@Override
public void registerListener(IOpenListener listener)

方法名	参数	是否必填	描述
registerListener	IOpenListener	是	继承自IOpenListener.Stub的回调

5.注销数据回流监听

/**
     * 注销数据回流
     * @param listener
     */
    @Override
    public void unRegisterListener(IOpenListener listener)

方法名	参数	是否必填	描述
unRegisterListener	IOpenListener	是	继承IOpenListener.Stub的回调

6.获取sdk版本号

/**
     * 获取sdk版本号
     * @return
     */
    @Override
    public int getVersionCode()

7.获取sdk版本名

/**
     * 获取sdk版本名
     * @return
     */
    @Override
    public String getVersionName()

8.获取设备信息

/**
 * 获取设备基本信息
 * @return
 */
@Override
public String getDeviceBaseInfo()

返回结果：

{"sn":"090902190730KN0015","romVersion":20124,"romVersionName":"2.1.24.0","appVersion":2158,"appVersionName":"V1001.2.0.0-xtest"}

参数名	类型	描述
sn	String	设备唯一标记
romVersion	long	rom版本号
romVersionName	String	rom版本名
appVersion	int	魔点app版本号
appVersionName	String	魔点app版本名

9.获取设备device host模式

 /**
     * 获取设备device host模式
     * @return 1 host模式 0 device模式 -1 获取失败
     */
    @Override
    public int getDeviceHostMode()

设备系统每次启动默认处于host模式
device模式：usb线连接adb时设备必须处于device模式
host模式：以太网正常工作时必须处于host模式

10.切换设备device host模式

/**
     * 切换设备device host 模式
     * @param model 1 host模式 0 device模式
     */
    @Override
    public void swicthDeviceHostMode(int model)

每次切换模式后，因为切换存在延迟，若需要通过getDeviceHostMode获取当前模式，需要延迟1秒以上，否则获取到的状态可能有误

11.开启网络adb

/**
     * 是否开启网络adb
     * @param enable true开启 false 关闭
     */
    @Override
    public void enableAdb(boolean enable)

12.开启设备调试输出

/**
     * 是否设备日志logcat输出
     * @param enable true开启 false 关闭
     */
    @Override
    public void enableLogcat(boolean enable)

13.设置刷脸模式

/**
     * 设置识别模式
     * @param mode 1多人识别 2单人识别
     */
    @Override
    public void setRecognizeMode(int mode)

方法名	参数	类型	是否必填	描述
setRecognizeMode	mode	int	-	1多人识别 2单人识别

14.调用刷脸

/**
     * 调用刷脸
     * @param timeOut 刷脸超时时间
     */
    @Override
    public void detectFace(int timeOut)

方法名	参数	类型	是否必填	描述
detectFace	timeOut(秒)	int	否	跳转到刷脸页后，超时自动返回三方应用,默认60秒

结果通过IOpenListener回调返回
回调action: detect_face
识别成功json:

{"data":{"personId":"10021","personName":"xxx","sceneType":0,"temperature":0.0},"message":"识别成功","result":"200"}

识别失败json:

{"message":"识别失败，陌生人","result":"400"}

15.调用刷卡

/**
     * 调用刷卡
     * @param timeOut 刷卡超时时间
     */
    @Override
    public void swipCard(int timeOut)

方法名	参数	类型	是否必填	描述
swipCard	timeOut(秒)	int	否	跳转到刷卡页后，超时自动返回三方应用,默认60秒

结果通过IOpenListener回调返回
回调action: swipe_card
成功json:

{"data":"2037175851","result":"200","message":"刷卡成功"}

失败json:

{"message":"设备不支持刷卡","result":"400"}

16.调用扫码

/**
     * 调用扫码
     * @param timeOut 扫码超时时间
     */
    @Override
    public void scanQrCode(int timeOut)

方法名	参数	类型	是否必填	描述
scanQrCode	timeOut(秒)	int	否	跳转到扫码页后，超时自动返回三方应用,默认60秒

回调action: scan_qr_code
成功json:

{"data":"www.moredian.com","result":"200","message":"扫码成功"}

失败json:

{"message":"设备不支持扫码","result":"400"}

17.通过卡号获取人员信息

/**
     * 通过卡号获取用户信息
     * @param cardNo
     */
    @Override
    public void getUserInfoByCard(String bizNo, @NonNull String cardNo)

方法名	参数	类型	是否必填	描述
getUserInfoByCard	bizNo	String	否	业务流水号，需要保证唯一性，设置后魔点开放服务会携带该参数返回
getUserInfoByCard	cardNo	String	是	通过卡号获取用户信息，需要提前在魔点微应用绑定人员和卡号关系

回调action: get_user_info
成功json:

{"data":{"bizNo":"xxxxxxxxxxxxx"，"cardNum":"2037175851","dingUserId":"1000","id":32909,"name":"xxx","status":1},"message":"query card info success","result":"200"}

失败json:

{"message":"query card info fail","result":"400"}

18.重启设备

/**
     * 重启设备
     */
    @Override
    public void reboot()

19.开门

/**
     * 开门
     */
    @Override
    public void openDoor(boolean isUserDefaultTime, long openDoorTime)

方法名	参数	类型	是否必填	描述
openDoor	isUserDefaultTime	boolean	否	是否使用开放服务默认开门时间
openDoor	openDoorTime	Long	否	毫秒，自定义开门时间，isUserDefaultTime false生效

20.设备音量配置

设置了不在0-100范围内的数据，sdk会抛出异常，需要手动捕获

/**
     * 设置设备音量
     * @param volume 0-100内整数
     */
    @Override
    public void controlVolume(int volume)

方法名	参数	类型	是否必填	描述
controlVolume	volume	int	是	配置设备整体音量大小 范围：0-100

21.设备led补光灯亮度配置

设置了不在0-255范围内的数据，sdk会抛出异常，需要手动捕获

/**
     * 设置led补光灯亮度
     * @param value 0-255内整数
     */
    @Override
    public void controlLed(int value)

方法名	参数	类型	是否必填	描述
controlLed	value	int	是	配置设备led亮度 范围：0-255

22.设备屏幕亮度配置

设置了不在0-255范围内的数据，sdk会抛出异常，需要手动捕获

/**
     * 设置屏幕亮度
     * @param value 0-255内整数
     */
    @Override
    public void controlScreenLight(int value)

方法名	参数	类型	是否必填	描述
controlScreenLight	value	int	是	配置设备屏幕亮度 范围：0-255

23.离线语音合成和播放

/**
     * 离线语音合成播放
     * @param content
     */
    @Override
    public void playTts(String content)

回调action: play_tts
成功json:

{"message":"播放成功","result":"200"}

失败json:

{"message":"TTS组件未初始化","result":"400"}

24.无线网络配置

/**
     * 无线网络配置
     * @param timeOut 无线网络配置超时时间
     */
    @Override
    public void startWifiSet(int timeOut)

方法名	参数	类型	是否必填	描述
startWifiSet	timeOut(秒)	int	否	跳转到无线网配置界面，超时自动返回三方应用,默认60秒

25.有线网络配置

/**
     * 有线网络配置
     * @param timeOut 有线网络配置超时时间
     */
    @Override
    public void startEtherSet(int timeOut)

方法名	参数	类型	是否必填	描述
startEtherSet	timeOut(秒)	int	否	跳转到有线网配置界面，超时自动返回三方应用,默认60秒

回调action: start_ethernet
成功直接跳转
失败json:

{"message":"网线未插入","result":"400"}

26.应用日志存储

/**
* 保存日志
* @param log 日志信息
*/
@Override
public void saveLog(String log)

四、行业终端应用接入指南

4.1、接入流程

环境搭建

第三方应用开发者拿到魔点开放sdk后，需要把aar文件置于libs目录下，通过gradle加载开放sdk

implementation(name: 'base_open_1.0.0_1', ext: 'aar')

启动配置

调用开放sdk前需要在AndroidManifest.xml文件中配置启动界面的action，魔点应用会在每次启动后判断第三方应用是否存在，如果存在则会拉起第三方应用

<activity android:name=".MainActivity"
        android:exported="true"
        android:launchMode="singleTask">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
        <intent-filter>
            <action android:name="com.moredian.open.start" />
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </activity>

sdk初始化

调用魔点开放open sdk之前，需要通过MdOpenServer初始化sdk,需传入appId和appKey，可通过魔点开放平台->终端安卓应用->行业终端应用-创建项目（应用）获取

private void initOpenServer() {
  MdOpenServer.getInstance().init(this,this);
}

数据监听

初始化成功后再去注册数据回流监听

@Override
    public void onInitCallBack(boolean isSuccess, String message) {
        Log.d(TAG, "onInitCallBack: isSuccess="+isSuccess+",message="+message);      
    }

sdk注销

应用或者界面销毁，初始化回调失败，需要通过unRegisterListener注销历史的回流监听，否则下次再次注册，会返回多条相同的数据

4.2、业务接口

名词解释

OpenInitListener 初始化回调

private class OpenListener extends IOpenListener.Stub {
        @Override
        public void dataCallBack(String action, String result) throws RemoteException

回调方法	参数	类型	描述
dataCallBack	action	string	发起调用open sdk的动作
dataCallBack	result	string	json格式回调

AuthCallBack 授权回调

public interface AuthCallBack {
   void onAuthBack(boolean var1, String var2);
}

回调方法	参数	类型	描述
onAuthBack	var1	boolean	授权是否成功
onAuthBack	var2	string	授权结果信息

OpenResultListener 数据回调

public interface OpenResultListener {
  void resultCallBack(String action, String result);
}

回调方法	参数	类型	描述
resultCallBack	action	string	调用的开放方法
resultCallBack	result	string	返回结果

1. sdk初始化

/**
     * sdk初始化
     * @param context 系统上下文
     * @param openInitListener 初始化回调
     */
    @Override
    public void init(@NonNull Context context, OpenInitListener openInitListener)

方法名	参数	类型	是否必填	描述
init	context	Context	是	上下文
init	openInitListener	OpenInitListener	是	初始化回调

2. 获取授权

/**
 * @param appId 终端开放平台创建的appId
 * @param appKey 终端开放平台创建的appKey
 */
@Override
public void getAuth(String appId, String appKey, AuthCallBack authCallBack)

方法名	参数	类型	是否必填	描述
getAuth	appId	string	是	终端开放平台创建的appId
getAuth	appKey	string	是	终端开放平台创建的appKey
getAuth	authCallBack	AuthCallBack	是

3. sdk注销

应用销毁后应及时注销sdk，注销后，sdk会断开连接，同时释放持有的资源

/**
     * sdk注销
     */
    @Override
    public void release()

4. 注册数据回流监听

/**
* 注册数据回流
* @param listener
*/
@Override
public void registerListener(IOpenListener listener)

方法名	参数	是否必填	描述
registerListener	IOpenListener	是	继承自IOpenListener.Stub的回调

5. 注销数据回流监听

/**
     * 注销数据回流
     * @param listener
     */
    @Override
    public void unRegisterListener(IOpenListener listener)

方法名	参数	是否必填	描述
unRegisterListener	IOpenListener	是	继承IOpenListener.Stub的回调

6. 获取sdk版本号

/**
     * 获取sdk版本号
     * @return
     */
    @Override
    public int getVersionCode()

7. 获取sdk版本名

/**
     * 获取sdk版本名
     * @return
     */
    @Override
    public String getVersionName()

8. 获取设备信息

/**
 * 获取设备基本信息
 * @return
 */
@Override
public String getDeviceBaseInfo()

返回结果：{“sn”:”090902190730KN0015”,”romVersion”:20124,”romVersionName”:”2.1.24.0”,”appVersion”:2158,”appVersionName”:”V1001.2.0.0-xtest”}

参数名	类型	描述
sn	String	设备唯一标记
romVersion	long	rom版本号
romVersionName	String	rom版本名
appVersion	int	魔点app版本号
appVersionName	String	魔点app版本名

9. 获取设备device host模式

 /**
     * 获取设备device host模式
     * @return 1 host模式 0 device模式 -1 获取失败
     */
    @Override
    public int getDeviceHostMode()

设备系统每次启动默认处于host模式

device模式：usb线连接adb时设备必须处于device模式

host模式：以太网正常工作时必须处于host模式

10. 切换设备device host模式

/**
     * 切换设备device host 模式
     * @param model 1 host模式 0 device模式
     */
    @Override
    public void swicthDeviceHostMode(int model)

每次切换模式后，因为切换存在延迟，若需要通过getDeviceHostMode获取当前模式，需要延迟1秒以上，否则获取到的状态可能有误

11. 开启网络adb

/**
     * 是否开启网络adb
     * @param enable true开启 false 关闭
     */
    @Override
    public void enableAdb(boolean enable)

12. 开启设备调试输出

/**
     * 是否设备日志logcat输出
     * @param enable true开启 false 关闭
     */
    @Override
    public void enableLogcat(boolean enable)

13. 设置刷脸模式

/**
     * 设置识别模式
     * @param mode 1多人识别 2单人识别
     */
    @Override
    public void setRecognizeMode(int mode)

方法名	参数	类型	是否必填	描述
setRecognizeMode	mode	int		1多人识别 2单人识别

14. 调用刷脸

/**
     * 调用刷脸
     * @param timeOut 刷脸超时时间
     */
    @Override
    public void detectFace(int timeOut)

方法名	参数	类型	是否必填	描述
detectFace	timeOut(秒)	int	否	跳转到刷脸页后，超时自动返回三方应用,默认60秒

结果通过IOpenListener回调返回

回调action: detect_face

识别成功json:

{“data”:{“personId”:”10021”,”personName”:”xxx”,”userType”:1},”message”:”识别成功”,”result”:”200”}

识别失败json:

{“message”:”识别失败，陌生人”,”result”:”400”}

15. 刷卡回调

{“data”:”0123456789”,”message”:”刷卡成功”,”result”:”200”}

16. 调用扫码

/**
     * 调用扫码
     * @param timeOut 扫码超时时间
     */
    @Override
    public void scanQrCode(int timeOut)

方法名	参数	类型	是否必填	描述
scanQrCode	timeOut(秒)	int	否	跳转到扫码页后，超时自动返回三方应用,默认60秒

回调action: scan_qr_code

成功json:

{“data”:”www.moredian.com”,”result”:”200”,”message”:”扫码成功”}

失败json:

{“message”:”设备不支持扫码”,”result”:”400”}

17. 通过卡号获取人员信息

/**
     * 通过卡号获取用户信息
     * @param cardNo
     */
    @Override
    public void getUserInfoByCard(String cardNo)

方法名	参数	类型	是否必填	描述
getUserInfoByCard	cardNo	String	是	通过卡号获取用户信息，需要提前在魔点微应用绑定人员和卡号关系

回调action: get_user_info

成功json:

{“data”:{“cardNum”:”2037175851”,”dingUserId”:”1000”,”id”:32909,”name”:”xxx”,”status”:1},”message”:”query card info success”,”result”:”200”}

失败json:

{“message”:”query card info fail”,”result”:”400”}

18. 重启设备

/**
     * 重启设备
     */
    @Override
    public void reboot()

19. 开门

/**
     * 开门
     */
    @Override
    public void openDoor(boolean isUserDefaultTime, long openDoorTime)

方法名	参数	类型	是否必填	描述
openDoor	isUserDefaultTime	boolean	否	是否使用开放服务默认开门时间
openDoor	openDoorTime	Long	否	毫秒，自定义开门时间，isUserDefaultTime false生效

20. 设备音量配置

设置了不在0-100范围内的数据，sdk会抛出异常，需要手动捕获

/**
     * 设置设备音量
     * @param volume 0-100内整数
     */
    @Override
    public void controlVolume(int volume)

方法名	参数	类型	是否必填	描述
controlVolume	volume	int	是	配置设备整体音量大小 范围：0-100

21. 设备led补光灯亮度配置

设置了不在0-255范围内的数据，sdk会抛出异常，需要手动捕获

/**
     * 设置led补光灯亮度
     * @param value 0-255内整数
     */
    @Override
    public void controlLed(int value)

方法名	参数	类型	是否必填	描述
controlLed	value	int	是	配置设备led亮度 范围：0-255

22. 设备屏幕亮度配置

设置了不在0-255范围内的数据，sdk会抛出异常，需要手动捕获

/**
     * 设置屏幕亮度
     * @param value 0-255内整数
     */
    @Override
    public void controlScreenLight(int value)

方法名	参数	类型	是否必填	描述
controlScreenLight	value	int	是	配置设备屏幕亮度 范围：0-255

23. 离线语音合成和播放

/**
     * 离线语音合成播放
     * @param content
     */
    @Override
    public void playTts(String content)

回调action: play_tts

成功json:

{“message”:”播放成功”,”result”:”0”}

失败json:

{“message”:”TTS组件未初始化”,”result”:”400”}

24. 无线网络配置

/**
     * 无线网络配置
     * @param timeOut 无线网络配置超时时间
     */
    @Override
    public void startWifiSet(int timeOut)

方法名	参数	类型	是否必填	描述
startWifiSet	timeOut(秒)	int	否	跳转到无线网配置界面，超时自动返回三方应用,默认60秒

25. 有线网络配置

/**
     * 有线网络配置
     * @param timeOut 有线网络配置超时时间
     */
    @Override
    public void startEtherSet(int timeOut)

方法名	参数	类型	是否必填	描述
startEtherSet	timeOut(秒)	int	否	跳转到有线网配置界面，超时自动返回三方应用,默认60秒

回调action: start_ethernet

成功直接跳转

失败json:

{“message”:”网线未插入”,”result”:”400”}