智慧通行SDK

2017年12月

1．引言

1.1．编写之前

本文档为第三方APP提供了接入特斯联通行SDK的能力，使第三方APP具有智能通行、电子钥匙、访客管理等功能。

SDK包含如下功能：

登录

登出

增值服务

获取授权列表

蓝牙、NFC开锁(Android)、Ibeacon开锁(IOS)、远程开锁

一次性密码

按次授权、时间段授权、永久授权等功能

1.2．关于接入提供SDK 接入流程

提供接入SDK DEMO、SDK aar文件

提供接入文档

1.3．整体架构

第三方APP、特斯联SDK数据交互流程：

第三方用户登录绿地App

第三方服务器调用特斯联服务器，获取当前用户的授权Token。接口说明

特斯联服务器校验并生成授权Token，返回给第三方服务器

第三方返回Token给App

第三方App将Token传给特斯联SDK进行数据初始化

特斯联SDK从特斯联服务器拉取钥匙

1.4．SDK包含内容

本SDK使用android studio开发，支持Android 4.0以上版本。

app module：提供接入流程的配置、方法调用等。

aars文件夹：以aar形式提供特斯联开发者SDK，主要是出口类为TerminusOpenSDK。

2．接口说明

Sdk中使用到的相关实体类，开发者需要在开发过程中，根据这些实体类的属性，开发业务相关的功能。

2.1．TerminusOpenAuthBean

设备信息实体

public DeviceInfo mDeviceInfo;

设备授权信息

public AuthInfo mAuthInfo;

2.1.1．TerminusOpenAuthBean. DeviceInfo

public String DeviceId; 设备唯一标示ID

public String Mac; 设备Mac地址

public String Secret; 设备密码

public int FeatureBits; 设备功能特性位

public String Location; 设备安装位置备注

public String Cipher; 钥匙开门密文

public boolean isSupportTalk() ; 是否支持可视对讲

public boolean isSupportRemote(); 是否支持远程开锁

public boolean isOncePassword(); 是否支持单次密码功能

public boolean isSupportNfcOpen(); 是否支持NFC开锁功能

public boolean isSupportFinger() ; 是否支持指纹开锁功能

public boolean isSupportBeacon() ; 是否支持IBeacon开锁功能

public boolean isSupportXinDun(); 是否支持芯盾加密功能

2.1.1．TerminusOpenAuthBean. DeviceInfo

public String AuthId; 授权ID

public long StartTime; 钥匙开始时间

public long EndTime; 钥匙结束时间

public int Times; 授权次数

public int UseTimes; 当前使用的次数,

public int NumberLimit; 是否限制分享的次数 0 不受限制；1受限制

public int TimeLimit; 是否限制永久授权 0 不受限制，1受限制

public int IsSecond; 是否是二次分享 0否 1是

public boolean isSupportForeverAuthor() ; 是否支持永久授权

public boolean isSupportTimesAuthor() ; 是否支持次数授权

public boolean isSupportTimesOpen() ; 是否支持次数开门

2.2．ScanDevice

String name; 蓝牙设备名称

String address; 蓝牙设备地址

int[] rssiArray; 蓝牙设备信号缓存值集合

public BluetoothDevice device; 蓝牙设备实体

public String getName(); 获取蓝牙设备名称

public String getAddress(); 获取蓝牙设备地址

public int getRssi() ; 获取Rssi

3．接入

3.1．接入准备

3.1.1．引入aar文件

在app module中新建aars文件夹，把DEMO中openapp module下aars文件下中的terminussdk_x.x.x.aar(x.x.x为当前sdk版本号)。

在app的build.gradle文件中加入以下代码：

repositories {

mavenCentral()

flatDir {

dirs 'aars'

}

}

dependencies {

//xxxx 自己项目的依赖

compile compile(name: 'terminussdk_1.5.0', ext: 'aar')

}

3.1.2．设置ProductKey

在项目AndroidManifest.xm中添加ProductKey

android:name="TERMINUS_PRODCUTKEY"

android:value="申请的ProductKey"/>

3.1.3．环境切换、sdk初始化(建议在Application)

/**

初始化sdk，标识位、安全校验、钥匙、nfc等。

@param debugLog 设置是否debug模式

@param onlineServer 设置是否线上环境

*/

public void init(boolean debugLog, boolean onlineServer)

3.1.4．混淆-keep class com.terminus.lock.sdk.*{*;}

-keep class com.terminus.lock.library.*{*;}

3.1.5．Android 6.0动态权限申请

Android 6.0新增了运行时权限动态检测，SDK需ACCESS_COARSE_LOCATION权限。

Android6.0系统为targetSdkVersion小于23的应用默认授予了所申请的所有权限，所以如果App使用的targetSdkVersion低于23，可以正常运行。但如果用户在设置中取消了授予的权限，或者App使用的targetSdkVersion为23以上，需要在App代码中处理。

用户可自行网上搜索动态权限申请的方法。

3.2．sdk提供的功能以及调用说明

SDK的出口类为TerminusOpenSdk，以下功能均由此类提供。

3.2.1． 获取TerminusOpenSdk实例

/**

Gets instance.

@param context the context

@return the instance

*/

public static TerminusOpenSDK getInstance(Context context)

/**

初始化sdk，标识位、安全校验、钥匙、nfc等。

@param debugLog 设置是否debug模式

@param onlineServer 设置是否线上环境

*/

public void init(boolean debugLog, boolean onlineServer)

调用实例：

TerminusSDK.getInstance(getApplicationContext()).init(true,true)

3.2.2． 登录

/**

绑定账户到sdk，同时会更新账户的数据，

accessToken的获取方法参考接入文档，

建议定时拉取

@param accessToken 指定用户的token

@throws TerminusCheckException the terminus check exception

*/

public void login(String accessToken)

调用实例：

TerminusSDK.getInstance(getApplicationContext()).login(accessToken)

3.2.3．判断是否已经登录

/**

是否设置token

@return 是否登录 boolean

@throws TerminusCheckException the terminus check exception

*/

public boolean isLoggedIn() ;

调用实例：

TerminusSDK.getInstance(getApplicationContext()).isLoggedIn()

3.2.4．登出

/**

解除账户和sdk的绑定，同时清除相关的数据，包括钥匙、accesstoken等。

在app退出时，调用此方法

@throws TerminusCheckException the terminus check exception

*/

public void logout()

调用实例：

TerminusSDK.getInstance(getApplicationContext()).logout()

3.2.5．蓝牙扫描

蓝牙扫描流程，开始扫描、获取扫描结果、结束扫描。

开始扫描

/**

开始扫描。

@throws TerminusCheckException the terminus check exception

*/

public void startScan()

获取扫描结果

/**

获取扫描到的设备，建议每隔300ms取一次。

@return 当前周围所有可用设备 scan devices

@throws TerminusCheckException the terminus check exception

*/

public List getScanDevices()

结束扫描

/**

停止扫描

@throws TerminusCheckException the terminus check exception

*/

public void stopScan()

是否正在扫描

/**

是否正在扫描

@return boolean boolean

@throws TerminusCheckException the terminus check exception

*/

public boolean isScanning()

3.2.6．刷新当前用户的授权记录(拉取钥匙列表)

方法说明：

/**

获取当前用户的授权记录，须先login

@param callBack

*/

public void fetchKeys(FetchDataCallBack> callBack)

回调方法：

FetchDataCallBack> callBack

以授权记录集合回调。

调用实例：

TerminusOpenSDK.getInstance(getApplicationContext())

.fetchKeys(new FetchDataCallBack>() {

@Override

public void onSuccess(ArrayList data) {

//返回成功数据

}

@Override

public void onFailed(int errorCode, String msg) {

//调用失败回调

}

});

3.2.7．获取当前用户所有设备

/**

获取所有钥匙数据

@return 登录用户所有钥匙 all keys

@throws TerminusCheckException the terminus check exception

*/

public List getAllKeys()

3.2.8．蓝牙开锁

通过蓝牙协议开锁。

方法说明：

/**

蓝牙开锁

通过蓝牙协议开锁

@param authBean {@link TerminusOpenAuthBean} 授权实体

@param listener 开锁结果

@throws TerminusCheckException the terminus check exception

*/

public void openDoor(@NonNull final TerminusOpenAuthBean authBean,

final OpenDoorCallBack listener)

调用实例：

TerminusOpenSDK.getInstance(getApplicationContext())

.openDoor(keyBean, new OpenDoorCallBack() {

@Override

public void onSuccess() {

//蓝牙开锁成功

}

@Override

public void onFail(int errcode) {

//蓝牙开锁失败

}

});

3.2.9．远程开锁

通过网络给设配发送开锁指令，设配接收到开锁指令开锁。

方法说明：

/**

远程开锁(钥匙不需要在附近)

通过网络给设配发送开锁指令，设配接收到开锁指令开锁。

@param authBean {@link TerminusOpenAuthBean} 授权实体

@param cmd 下发命令类型{@link com.terminus.lock.sdk.TslConstants.RemoteControlCmd}

@param data 透传指令 与cmd配合使用

@param listener

@throws TerminusCheckException

*/

public void openDoor(@NonNull final TerminusOpenAuthBean authBean,

TslConstants.RemoteControlCmd cmd,

String data, final OpenDoorCallBack listener)

调用实例：

TerminusSDK.getInstance(mContext).openDoor(key.getKey(),

false, 搜索超时时间, new OpenDoorCallBack() {

@Override

public void onSuccess() {

//开门成功

}

@Override

public void onFail(int errcode) {

// 开门失败

}

});

3.2.10．是否正在开门(用于蓝牙开门)

方法说明：

/**

指定keybean是否正在开锁

@param authBean {@link TerminusOpenAuthBean} 授权实体

@return

@throws TerminusCheckException the terminus check exception

*/

public boolean isOpening(@NonNull final TerminusOpenAuthBean authBean)

调用实例：

TerminusOpenSDK.getInstance(getApplicationContext()).isOpening(keyBean);

3.2.11．双模开锁(蓝牙和网络)

方法说明：

/**

蓝牙&远程开锁

同时使用蓝牙和网络开锁，成功率更高、速度更快。用于支持远程开锁的设配

@param authBean {@link TerminusOpenAuthBean} 授权实体

@param needNearLock 是否要求设备在附近

@param timeout 开门超时时间与isNeedNearLock配合使用 单位/毫秒

@param listener 开锁结果监听器

@throws TerminusCheckException

*/

public void openDoor(@NonNull final TerminusOpenAuthBean authBean,

boolean needNearLock, long timeout,

final OpenDoorCallBack listener)

3.2.12．取消开门(用于蓝牙开门)

方法说明：

/**

取消开锁

@param authBean @link{TerminusOpenAuthBean} 授权实体

@throws TerminusCheckException the terminus check exception

*/

public void cancelOpenDoor(@NonNull final TerminusOpenAuthBean authBean)

调用实例：

TerminusOpenSDK.getInstance(getApplicationContext()).cancelOpenDoor(keyBean);

3.2.13． 一次性密码

一次性密码，用途特斯联设配，开发者平台生成一组开锁密码，下发至设配，第三方开发者可将此密码分享至需要操作设配的用户，用户可用此密码打开设配。

方法说明：

/**

一次性密码授权(仅适用于特斯联设备)

@param key {@link TerminusOpenAuthBean} 授权实体

@param callBack

@throws TerminusCheckException

*/

public void shareOneOffWithKey(@NonNull TerminusOpenAuthBean key,

@NonNull FetchDataCallBack callBack)

调用实例：

TerminusOpenSDK.getInstance(getApplicationContext())

.shareOneOffWithKey(keyBean, new FetchDataCallBack() {

@Override

public void onSuccess(TslOneTimeAuthorizeResponse data) {

//分享成功

}

@Override

public void onFailed(int errorCode, String msg) {

//分享失败

}

});

3.2.14． 时间段授权

次数授权、时间段授权、永久授权，用于将此用户的钥匙，按不同方式授权给另一名用户。

方法说明：

/* 时间段授权

@param key {@link TerminusOpenAuthBean} 授权实体

@param phone 授权人电话号码

@param startTime 授权开始时间

@param endTime 授权结束时间

@param callBack

@throws TerminusCheckException

*/

public void shareTimeQuantumWithKey(@NonNull TerminusOpenAuthBean key,

@NonNull String phone,

long startTime,

long endTime,

@NonNull FetchDataCallBack callBack)

调用实例：

TerminusOpenSDK.getInstance(getApplicationContext())

.shareTimeQuantumWithKey(key, phone, 1125997780,

11259988870, new FetchDataCallBack() {

@Override

public void onSuccess(String data) {

//分享成功

}

@Override

public void onFailed(int errorCode, String msg) {

//分享失败

}

});

3.2.15． 永久授权

次数授权、时间段授权、永久授权，用于将此用户的钥匙，按不同方式授权给另一名用户

方法说明：

/**

永久授权授权

@param key {@link TerminusOpenAuthBean} 授权实体

@param phone 授权人电话号码

@param callBack

@throws TerminusCheckException

*/

public void sharePerpetualWithKey(@NonNull TerminusOpenAuthBean key,

@NonNull String phone,

@NonNull FetchDataCallBack callBack)

调用实例：

TerminusOpenSDK.getInstance(getApplicationContext())

.sharePerpetualWithKey(key, phone, new FetchDataCallBack() {

@Override

public void onSuccess(String data) {

//分享成功

}

@Override

public void onFailed(int errorCode, String msg) {

//分享失败

}

});

4．错误说明状态码

内容

100001

3s前已开门

100002

操作太频繁，请稍后重试

110000

正在重试

3006

设配不支持4.0蓝牙

4001

密码错误

4002

门锁已清除

4003

室内已反锁

4004

钥匙已禁用

4005

钥匙配对已满

4009

请按设置键

4010

非管理员，无权操作

6001

密码格式错误

8001

蓝牙不可用

110001

连接超时

110002

连接超时，请重试

100003

不支持的操作

100004

设配返回数据错误