1. 插件接入步骤
1.1 项目引入插件
1.1.1 通过cocoapods方式
//在项目Podfile文件中，增加插件及指定版本的引入
pod 'QNSDK', '2.29.0' //此处版本号可根据github中显示的最新版本进行引入
1.1.2 通过carthage方式
//在项目Cartfile文件中，增加插件引入
github "https://github.com/YolandaQingniu/sdk-ios-demo.git"
1.1.3 手动导入方式
1. 将.a文件放置项目中的指定位置
2. 在【TARGETS】-> 【Build Setting】->【Search Paths】->【LibrarySearch Paths】中添加SDK路径
3. 配置链接器 【TARGETS】-> 【Build Setting】-> 【Linking】-> 【Other Linker Flags】中添加 -ObjC、-all_load、-force_load [SDK路径] 其中之一
1.2 配置项目蓝牙权限使用说明
在项目的Info.plist文件中，增加 Privacy - Bluetooth Peripheral Usage Description、Privacy - Bluetooth Always Usage Description 键，进行蓝牙的使用说明
1.3 导入插件API头文件
#import <QNSDK/QNDeviceSDK.h>
1.4 初始插件
//获取项目中授权文件地址
NSString *file = [[NSBundle mainBundle] pathForResource:@"123456789" ofType:@"qn"];
//实例化插件, QNBleApi为单例对象
QNBleApi *bleApi = [QNBleApi sharedBleApi];
//获取插件授权
[bleApi initSdk:@"123456789" firstDataFile:file callback:^(NSError *error) {
if(error) {
//监听异常回调
}
}];
1.5 监听系统蓝牙状态变化(QNBleStateListener)
/*
typedef NS_ENUM(NSUInteger, QNBLEState) {
QNBLEStateUnknown = 0, //未知状态
QNBLEStateResetting = 1, //系统蓝牙正在重置
QNBLEStateUnsupported = 2, //系统不支持蓝牙使用
QNBLEStateUnauthorized = 3, //未授权蓝牙使用
QNBLEStatePoweredOff = 4, //系统蓝牙处于关闭状态
QNBLEStatePoweredOn = 5, //系统蓝牙处于开启状态
};
*/
- (void)onBleSystemState:(QNBLEState)state {
}
bleApi.bleStateListener = self;
1.6 监听扫描状态的变化(QNBleDeviceDiscoveryListener)
//启动扫描时，会回调该函数
- (void)onStartScan {
}
//停止扫描是，会回调该函数
- (void)onStopScan {
}
//当启动扫描，扫描到设备时会回调该函数。此处仅回调所支持的设备
- (void)onDeviceDiscover:(QNBleDevice *)device {
}
bleApi.discoveryListener = self；
1.7 监听设备连接状态变化(QNBleConnectionChangeListener)
//设备正在连接中回调
- (void)onConnecting:(QNBleDevice *)device {
}
//设备连接成功回调
- (void)onConnected:(QNBleDevice *)device {
}
//设备通讯服务已搜索完成，此处一般不涉及逻辑处理
- (void)onServiceSearchComplete:(QNBleDevice *)device {
}
//设备连接失败，会回调失败异常信息
- (void)onConnectError:(QNBleDevice *)device error:(NSError *)error {
}
//设备可以进行交互,即可以下发设备对应的操作指令
- (void)onStartInteracting:(QNBleDevice *)device {
}
//设备正在断开蓝牙连接
- (void)onDisconnecting:(QNBleDevice *)device {
}
//设备已断开
- (void)onDisconnected:(QNBleDevice *)device {
}
1.8 监听设备数据交互(QNUserScaleDataListener)
/* 秤端交互过程状态变化
typedef NS_ENUM(NSInteger, QNScaleState) {
QNScaleStateDisconnected = 0, //未连接
QNScaleStateLinkLoss = -1, //失去连接
QNScaleStateConnected = 1, //已连接
QNScaleStateConnecting = 2, //正在连接
QNScaleStateDisconnecting = 3, //正在断开
QNScaleStateStartMeasure = 4, //正在测量
QNScaleStateRealTime = 5, //正在测量体重
QNScaleStateBodyFat = 7, //正在测量生物阻抗
QNScaleStateMeasureCompleted = 9, //测量完成
}; 仅需关注该类状态
*/
- (void)onScaleStateChange:(QNBleDevice *)device scaleState:(QNScaleState)state {
}
/* 秤端行为状态变化
typedef NS_ENUM(NSInteger, QNScaleEvent) {
QNScaleEventRegistUserSuccess = 4, //注册用户成功
QNScaleEventRegistUserFail = 5, //注册用户失败
QNScaleEventVisitUserSuccess = 6, //访问用户成功
QNScaleEventVisitUserFail = 7, //访问用户失败
QNScaleEventDeleteUserSuccess = 8, //删除用户成功
QNScaleEventDeleteUserFail = 9, //删除用户失败
QNScaleEventSyncUserInfoSuccess = 10, //同步用户信息成功
QNScaleEventSyncUserInfoFail = 11, //同步用户信息失败
QNScaleEventUpdateIdentifyWeightSuccess = 12, //更新用户识别体重成功
QNScaleEventUpdateIdentifyWeightFail = 13, //更新用户识别体重失败
};仅需关注该类状态
*/
- (void)onScaleEventChange:(QNBleDevice *)device scaleEvent:(QNScaleEvent)scaleEvent {
}
//向设备中指定用户坑位反写上一笔有效测量数据hmac(指体脂秤大于0的数据hmac)。该方式有助于用户生物阻抗测量稳定性，若无需加强稳定性可直接返回nil
- (NSString *)getLastDataHmac:(QNBleDevice *)device user:(QNUser *)user {
//从用户测量测量历史数据中，获取最后一条体脂率大于0的测量数据中的hmac。hmac由测量数据产生，见QNScaleData对象
NSString *hmac = lastVailDataHmac;
return hmac;
}
//向秤端注册用户成功，回调秤端分配的用户坑位
- (void)registerUserComplete:(QNBleDevice *)device user:(QNUser *)user {
//注册用户时，秤端分配的坑位。app端应将该坑位、用户id、设备mac进行关联保存。下次该用户连接该设备时需用到该index进行秤端用户访问测量
int index = user.index;
}
/*
设备测量过程实时重量的回调
@param weight 实时体重，单位kg
*/
- (void)onGetUnsteadyWeight:(QNBleDevice *)device weight:(double)weight {
}
/*
设备测量完成测量数据回调
@param scaleData 测量数据
*/
- (void)onGetScaleData:(QNBleDevice *)device data:(QNScaleData *)scaleData {
//测量完成获取完整测量数据
NSDate *measureData = scaleData.measureTime;//测量时间
double weight = scaleData.weight;//测量体重
NSArray <QNScaleItemData *> *allTarget = [scaleData getAllItem];
for (QNScaleItemData *item in allTarget) {
item.type //指标类型，见QNScaleType
item.value //指标数值
}
}
/*
当前访问用户存储数据及未知存储回调
@param storedDataList 存储数据列表，通过QNScaleStoreData对象中的isDataComplete判断是否为未知测量数据，false为未知测量数据，true为已知测量数据
*/
- (void)onGetStoredScale:(QNBleDevice *)device data:(NSArray <QNScaleStoreData *> *)storedDataList {
//对于未知测量数据，可通知相关用户，让用户选择这笔数据是否是自己的
NSMutableArray<QNScaleStoreData *> *unknowStoreDataList = [NSMutableArray array];
for (QNScaleStoreData *storeData in storedDataList) {
if（!storeData.isDataComplete）{
[unknowStoreDataList addObject:storeData];
} else {
//已知当前用户的存储数据，该存储数据可直接归属到该用户下
QNScaleData *scaleData = [storeData generateScaleDataWithLastEightHmac: nil];
for (QNScaleItemData *item in allTarget) {
item.type //指标类型，见QNScaleType
item.value //指标数值
}
}
}
}
1.9 扫描周围设备
[bleApi startBleDeviceDiscovery:^(NSError *error) {
}];
1.10 连接设备
//建议先停止扫描
[_bleApi stopBleDeviceDiscorvery:^(NSError *error) { }];
//设置秤端单位
QNConfig *sdkConfig = [QNConfig sharedConfig];
sdkConfig.unit = QNUnitKG;
[sdkConfig save];
QNUserScaleConfig *config = [[QNUserScaleConfig alloc] init];
//已注册的秤端用户列表，在本次连接时，会向秤端删除该数组不包含的秤端用户
NSMutableArray<QNUser *> *deviceUserList = [NSMutableArray array];
config.userlist = deviceUserList;
//本次连接的秤端用户
QNUser *user = [[QNUser alloc] init];
user.height = 170；//用户身高，单位cm
user.gender = @"male"；//用户性别，"male" 男性，"female" 女性
user.birthday = [NSDate dateWithTimeIntervalSince1970:631199317];//用户生日
user.index = 1; //用户坑位，该值由向秤端注册用户时，秤端返回，见registerUserComplete回调函数。若本次连接为该设备新用户需要向用户注册，则该属性无需填写
config.curUser = user；
//是否使用访客(即无需向秤端注册用户，秤端不会保存该用户的信息), 注意该字段与user.index中互斥，优先取isVisitor
config.isVisitor = false;
[bleApi connectUserScaleDevice:device config:config callback:^(NSError *error) {
}];
1.11 断开设备连接
//若有需要，可主动调用断开设备连接方法
[bleApi disconnectDevice:nil callback:^(NSError *error) {
}];
1.12 未知存储数据计算
//未知存储数据归属用户的用户信息
QNUser *user = [[QNUser alloc] init];
user.height = 170；//用户身高，单位cm
user.gender = @"male"；//用户性别，"male" 男性，"female" 女性
user.birthday = [NSDate dateWithTimeIntervalSince1970:631199317];//用户生日
//hmac为本次未知测量数据中的hmac，即QNScaleStoreData中的hmac
//lastHmac为该用户上一笔体脂率大于0八电极测量数据中的hmac，即QNScaleData中的hmac。若用户无上一笔体脂率大于0八电极测量数据则可传nil
QNScaleData scaleData = [bleApi calculateScaleDataByHmac:user hmac:hmac lastEightHmac:lastHmac callback:^(NSError *error) {
}];
2. API
2.1 QNBleApi
插件实例对象，用于调用插件相关API
2.1.1 sharedBleApi
描述：构建QNBleApi对象单例，为初始化插件的唯一函数
返回值：QNBleApi
2.1.2 getConfig
描述：获取插件配置信息
返回值：
QNConfig
duration：扫描超时时间，默认为0，代表不会出现扫描超时；若设置该指端，在启动扫描指定时间内会自动停止扫描，需自行维护扫描的调用
unit：设置秤端用户单位，但发起设备连接时，会同步单位设置到秤端
- QNUnitKG、QNUnitLB、QNUnitJIN、QNUnitStLb、QNUnitSt
showPowerAlertKey：是否允许系统自动弹框蓝牙权限弹框，需要在initSdk函数前设置
2.1.3 initSdk:firstDataFile:callback:
描述：通过传递配置文件路径的方式初始化插件，调用该函数后，若QNConfig中设置的showPowerAlertKey为true，系统自动弹出询问权限的提示，该提示由系统自动发起
参数:
appId: YKB授权的APPID
dataFile：配置文件在项目中的相对路径
callback：函数调用结果回调
2.1.4 initSdk:dataFileContent:callback:
描述：通过传递配置文件内容的方式初始化插件，调用该函数后，若QNConfig中设置的showPowerAlertKey为true，系统自动弹出询问权限的提示，该提示由系统自动发起
2.1.5 getCurSystemBleState
描述：获取当前系统蓝牙状态
返回值:
- QNBLEState：QNBLEStateUnknown、QNBLEStateResetting、QNBLEStateUnsupported、QNBLEStateUnauthorized、QNBLEStatePoweredOff、QNBLEStatePoweredOn
2.1.6 startBleDeviceDiscovery:
描述：启动扫描周围设备
参数:
- callback：函数调用结果回调
2.1.7 stopBleDeviceDiscorvery:
描述：停止扫描周围设备
参数:
- callback：函数调用结果回调
2.1.8 connectUserScaleDevice:config:callback:
描述：发起指定设备连接
参数:
device：扫描到的设备，取自于QNBleDeviceDiscoveryListener中onDeviceDiscover函数回调的device对象
config：本次连接的配置信息
userlist：秤端已注册用户列表，未在该列表中的用户均会在本次连接的时候向设备删除
curUser：当前连接设备的用户
height：身高，单位cm
gender：性别，男-“male”；女-“female”
birthday：生日
index：秤端用户坑位，当本次连接为向秤端注册用户时，该字段无需赋值。若赋值则走访问设备用户流程
isVisitor：是否使用秤端访客测量，该字段优先级高
callback：函数调用结果回调
2.1.9 disconnectDevice:callback:
描述：断开当前连接的设备
参数:
device：当前连接的设备对象，可不赋值
callback：函数调用结果回调
2.1.10 calculateScaleDataByHmac:hmac:lastEightHmac:callback:
描述：重算测量数据，可用于未知存储数据计算，也可以用于对已知测量数据需要改为其他用户测量的数据重算
参数:
user：该笔测量数据归属的用户信息
height：身高，单位cm
gender：性别，男-“male”；女-“female”
birthday：生日
hmac：本次测量数据的hmac
lastEightHmac：该笔测量数据归属的用户的上一笔体脂率大于0的八电极测量数据，若无则赋nil
callback：函数调用结果
2.2 QNBleStateListener
系统蓝牙状态变化的回调监听
2.2.1 onBleSystemState
描述：当系统蓝牙发生变化时，通过该函数回调
参数:
- state：QNBLEState 状态类型
2.3 QNBleDeviceDiscoveryListener
2.3.1 onStartScan
描述：当启动扫描时回调该函数，如调用startBleDeviceDiscovery函数
2.3.2 onStopScan
描述：当停止扫描时回调该函数，如调用stopBleDeviceDiscorvery函数
2.3.3 onDeviceDiscover
描述：发现周围设备时回调，该函数仅回到YKB的设备
参数:
device：发现的设备
mac：设备mac地址，设备唯一标识
name：设备昵称
modeId：设备类型的标识
bluetoothName：设备蓝牙名
RSSI：设备型号强度
maxUserNum：设备支持最大注册用户数
registeredUserNum：设备已注册的用户数
2.4 QNBleConnectionChangeListener
2.4.1 onConnecting
描述：当设备处理正在连接时回调
参数:
- device：设备对象
2.4.2 onConnected
描述：当设备连接成功后回调
参数:
- device：设备对象
2.4.3 onDisconnecting
描述：当设备正在断开连接时回调
参数:
- device：设备对象
2.4.4 onDisconnected
描述：当设备已断开连接时回调
参数:
- device：设备对象
2.4.5 onConnectError:error:
描述：当设备连接异常时回调
参数:
device：设备对象
error：连接错误信息
2.4.6 onStartInteracting
描述：设备可通讯回调，在该函数之后可调用设备的一些API操作，如更新用户基础体重等
参数:
device：设备对象
error：连接错误信息
2.5 QNUserScaleDataListener
2.5.1 onScaleStateChange:scaleState:
描述：设备状态变化的回调，如连接状态、测量状态等
参数:
device：设备对象
state：设备状态
QNScaleStateDisconnected 未连接
QNScaleStateLinkLoss 失去连接
QNScaleStateConnected 已连接
QNScaleStateConnecting 正在连接
QNScaleStateDisconnecting 正在断开连接
QNScaleStateStartMeasure 正在测量
QNScaleStateRealTime 正在测量体重
QNScaleStateBodyFat 正在测量生物阻抗
QNScaleStateMeasureCompleted 测量完成
2.5.2 onScaleEventChange:scaleEvent:
描述：设备事件回调，如连接状态、测量状态等
参数:
device：设备对象
scaleEvent：设备事件类型
QNScaleEventRegistUserSuccess 注册用户成功
QNScaleEventRegistUserFail 注册用户失败
QNScaleEventVisitUserSuccess 访问用户成功
QNScaleEventVisitUserFail 访问用户失败
QNScaleEventDeleteUserSuccess 删除用户成功
QNScaleEventDeleteUserFail 删除用户失败
QNScaleEventSyncUserInfoSuccess 同步用户信息成功
QNScaleEventSyncUserInfoFail 同步用户信息失败
QNScaleEventUpdateIdentifyWeightSuccess 更新用户识别体重成功
QNScaleEventUpdateIdentifyWeightFail 更新用户识别体重失败
2.5.3 onGetBleVer:bleVer:
描述：设备固件版本信息回调
参数:
device：设备对象
bleVer：固件版本号
2.5.4 onGetUnsteadyWeight:weight:
描述：设备测量实时体重回调
参数:
device：device
weight：当前实时体重，单位kg
2.5.5 onGetScaleData:data:
描述：当前蓝牙连接测量结果的回调
参数:
device：device
scaleData：当前测量数据
2.5.6 onGetStoredScale:data:
描述：设备当前访问用户的已知存储数据和未知测量数据的回调，非当前访问坑位的用户存储数据不会回调
参数:
device：device
storedDataList：存储用户
weight：测量体重，单位kg
measureTime：测量时间
mac：设备mac地址
isDataComplete：是否是已知数据，true为已知，false为未知
hmac：测量数据hmac