brightBeacon

来自于:智石立即使用

registerAppKey startRanging stopRanging startMonitoring stopMonitoring monitorRegions isMonitorRegion sendLocalNotification startAdvertising stopAdvertising connectBeacon disconnectBeacon isBeaconConnected writeBeaconValues sendBeaconValue checkBeaconFirmwareUpdate updateBeaconFirmwareWithProgress resetBeacon

概述

brightBeacon是一个基于Web的API库,以便与iBeacon、brightBeacon设备互动。该SDK安装要求IOS6.0+iPhone4s以上、Android4.3及以上支持蓝牙低功耗(BLE)的设备。 brightBeacon是智石说(北京)科技有限公司提供给开发者使用的API库。

使用此模块 需要打开定位权限(IOS 7.0和Android 6.0及以后必要)、蓝牙权限

registerAppKey

注册并验证开发者appKey,申请地址:智石开放平台

registerAppKey({params},callback(ret, err))

params

key:

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true,验证成功
  3. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:无效的AppKey
  3. AppKey注册失败
  4. }

示例代码

  1. var bb;
  2. apiready = function() {
  3. bb = api.require('brightBeacon');
  4. };
  5. bb.registerAppKey({
  6. key: ""
  7. }, function(ret, err) {
  8. if (ret.status) {
  9. alert(JSON.stringify(ret))
  10. } else {
  11. alert(JSON.stringify(err))
  12. }
  13. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

startRanging

扫描iBeacon或brightBeacon蓝牙设备

startRanging({params}, callback(ret, err))

params

uuids:

  • 类型:uuid数组,扫描的设备UUID(推荐传入),留空或不传扫描所有设备(iOS有差异)
  • 描述:注意Android使用蓝牙,IOS扫描iBeacon都需要请求蓝牙定位权限(非GPS);另IOS在留空或不传该参数时,无法获得扫描设备的UUID参数,但能获取电量等参数,并支持连接、配置设备(由于IOS对iBeacon扫描和蓝牙扫描的严格区分导致)
  • 常用取值:
    • E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
    • FDA50693-A4E2-4FB1-AFCF-C6EB07647825
    • 任意标准UUID格式即可(如上)

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true||false
  3. list: [{
  4. uuid: //设备UUID,区域标识(IOS需此UUID包含在传入参数数组内)
  5. major: //设备主值,范围[0,65535]
  6. minor: //设备次值,范围[0,65535]
  7. rssi: //信号强度,和发射功率有关,范围约-20 ~ -100
  8. accuracy: //距离参考,由采样计算或rssi估算
  9. name: //设备名(IOS不传uuids才解析)
  10. txPower: //设备发射功率(IOS不传uuids才解析)
  11. txInterval: //设备发射频率,越低RSSI越稳定,耗电(IOS不传uuids才解析)
  12. mPower: //设备测量功率,1米处RSSI值,用于距离accuracy估算(IOS不传uuids才解析)
  13. battery: //设备电量(IOS不传uuids才解析)
  14. temperature: //设备温度(IOS不传uuids才解析)
  15. pMode: //设备是否加密(IOS不传uuids才解析)
  16. version: //设备硬件版本(IOS不传uuids才解析)
  17. firmware: //设备软件版本(IOS不传uuids才解析)
  18. mac: //设备蓝牙mac地址(IOS不传uuids才解析)
  19. broadcastMode://设备工作模式(0:仅iBeacon 2:实物网ID-取自uuid 3:实物网链接 4:0和2同时 5:0和3同时 6:2和3同时)(IOS不传uuids才解析)
  20. eddystoneUrl://设备谷歌实物网链接(IOS不传uuids才解析)
  21. },{
  22. ...
  23. }
  24. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error: 扫描错误信息
  3. }

示例代码

  1. var param = {
  2. "uuids": ["FDA50693-A4E2-4FB1-AFCF-C6EB07647825"]
  3. };
  4. bb.startRanging(param, function(ret, err) {
  5. if (ret && ret.status) {
  6. for (var i = 0; i < ret.list.length; i++) {
  7. var beacon = ret.list[i];
  8. //beacon.rssi 信号强度
  9. //beacon.accuracy 距离参考
  10. //beacon.major 主标识
  11. //beacon.minor 次标识
  12. //beacon.uuid iBeacon的UUID(IOS需此uuid在传入列表能获取)
  13. //beacon.mac 蓝牙设备mac地址(IOS在不传uuids能获取)
  14. ...更多参考以上字段列表说明
  15. }
  16. } else {
  17. alert(err.error);
  18. }
  19. }

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

stopRanging

停止扫描iBeacon、brightBeacon

stopRanging()

示例代码

  1. bb.stopRanging();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

startMonitoring

设备区域后台监听,如需支持后台回调检测,请在apiReady之后立即初始化callback通道,保证启动后区域回调成功,{params}可留空

startMonitoring({params}, callback(ret, err))

params(可选)

uuid:

  • 类型:字符串
  • 描述:监听区域设备uuid

major:

  • 类型:字符串
  • 描述:(可选项)监听区域设备主值

minor:

  • 类型:字符串
  • 描述:(可选项)监听区域设备次值

identifier:

  • 类型:字符串
  • 描述:区域标识,识别、覆盖相同标识区域(留空选择有效的uuid_major_minor格式生成)

in:

  • 类型:字符串
  • 描述:是否监听进入区域(仅IOS支持)

out:

  • 类型:字符串
  • 描述:是否监听离开区域(仅IOS支持)

display:

  • 类型:字符串
  • 描述:是否锁屏时检测区域状态(仅IOS支持)

callback(ret, err)(可选)

开启监听区域成功不会立即返回callback, 开启监听区域失败、或监测到设备区域变化时才返回此callback, 如果需要支持后台监听区域,请在apiReady之后立即初始化callback通道。 ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true //监听回调成功
  3. uuid: //区域uuid
  4. major: //区域主值(未监听为空)
  5. minor: //区域次值(未监听为空)
  6. identifier: //区域标识符(区域唯一标志)
  7. state: 1、进入区域 2、离开区域
  8. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:
  3. 未设置监听区域uuid
  4. major值不能超过65535!
  5. minor值不能超过65535!
  6. 未设置监听区域状态!
  7. 监听区域无效!
  8. 该设备没有蓝牙功能,无法进行ibeacon的相关操作!
  9. 此功能需要开启蓝牙
  10. }

示例代码

  1. var _param = {
  2. "uuid": _uuid,
  3. "major": _major,
  4. "minor": _minor,
  5. "in": isIn ? "1" : "0",
  6. "out": isOut ? "1" : "0",
  7. "display": isDisplay ? "1" : "0",
  8. "identifier": _identifier
  9. };
  10. bb.startMonitoring(_param, function(ret, err) {
  11. if (ret && ret.status) {
  12. if (ret.state) {
  13. var param = {
  14. "msg": (ret.state == 1 ? "进入区域通知" : "离开区域通知") + ret.uuid,
  15. "action": "立即查看",
  16. "userInfo": "自定义传输参数"
  17. };
  18. //此处发一个消息栏通知,实际或自定义动作
  19. bb.sendLocalNotification(param, function(ret1, err1) {
  20. if (ret1.status) {
  21. alert(JSON.stringify(ret1));
  22. } else {
  23. alert(err1.error);
  24. }
  25. });
  26. }
  27. } else {
  28. api.alert({
  29. title: '错误',
  30. msg: err.error,
  31. }, function(ret, err) {
  32. });
  33. }
  34. });

补充说明

iOS

  • 如果需要程序退出后持续监听,需要提醒用户打开位置权限->始终;并需在apiReady时候初始化后台回调callback:{@link startRanging(callback(ret,err)):}

android

  • 通过服务保持后台,部分自定义系统、优化软件会严格限制程序后台服务运行时间。

    可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

stopMonitoring

停止监听

stopMonitoring()

params

uuid:

  • 类型:字符串
  • 描述:监听区域设备uuid

major:

  • 类型:字符串
  • 描述:(可选,选则需uuid同传)监听区域设备主值

minor:

  • 类型:字符串
  • 描述:(可选,选则需uuid和major同传)监听区域设备次值

identifier:

  • 类型:字符串
  • 描述:区域标识,识别、覆盖相同标识区域(留空选择有效的uuid_major_minor格式生成)

示例代码

  1. bb.stopMonitoring({
  2. uuid: uuid,
  3. major: major,
  4. minor: minor
  5. }, function(ret, err) {
  6. alert(JSON.stringify(ret));
  7. alert(JSON.stringify(err));
  8. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

monitorRegions

获取当前监听中的区域

monitorRegions(callback(ret))

callback(ret)

ret.regions:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true
  3. uuid:
  4. major:
  5. minor:
  6. in:(限IOS有效)
  7. out: (限IOS有效)
  8. display:(限IOS有效)
  9. }

示例代码

  1. bb.monitorRegions(function(ret, err) {
  2. if(ret && ret.status) {
  3. var html = "";
  4. for(var i = 0; i < ret.regions.length; i++) {
  5. var region = ret.regions[i];
  6. //region.uuid
  7. //region.major
  8. //region.minor
  9. //region.in
  10. //region.out
  11. //region.display
  12. }else {
  13. alert(err.error);
  14. }
  15. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

isMonitorRegion

区域是否处于监听中,identifier和uuid_major_minor组合任选传入

isMonitorRegion({params}, callback(ret))

Params

uuid:

  • 类型:字符串
  • 描述:监听区域设备uuid

major:

  • 类型:字符串
  • 描述:(可选,选则需uuid同传)监听区域设备主值

minor:

  • 类型:字符串
  • 描述:(可选,选则需uuid和major同传)监听区域设备次值

identifier:

  • 类型:字符串
  • 描述:区域标识,识别、覆盖相同标识区域(留空选择有效的uuid_major_minor格式生成)

    示例代码

  1. bb.isMonitorRegion({
  2. "uuid": uuid,
  3. "major": major,
  4. "minor": minor
  5. }, function(ret) {
  6. alert(JSON.stringify(ret));
  7. })
  8. 或者:
  9. bb.isMonitorRegion({"identifier":xxx}, function(ret) {
  10. alert(JSON.stringify(ret));
  11. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

sendLocalNotification

显示消息到通知栏

sendLocalNotification({params}, callback(ret, err))

params

msg:

  • 类型:字符串
  • 描述:通知栏消息内容

action:

  • 类型:字符串
  • 描述:通知栏操作字段

useInfo:

  • 类型:字符串
  • 描述:自定义传输参数

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true
  3. }

示例代码

  1. bb.sendLocalNotification(param, function(ret1, err1) {
  2. if(ret1.status) {
  3. alert(JSON.stringify(ret1));
  4. } else {
  5. alert(err1.error);
  6. }
  7. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

startAdvertising

广播iBeacon,仅支持前台

startAdvertising({params}, callback(ret, err))

params

uuid:

  • 类型:字符串
  • 描述:广播设备uuid

major:

  • 类型:字符串
  • 描述:设备主值

minor:

  • 类型:字符串
  • 描述:设备次值

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:uuid不能为空
  3. 其他广播不支持或相关错误
  4. }

示例代码

  1. var param = {
  2. "uuid": _uuid,
  3. "major": _major,
  4. "minor": _minor
  5. };
  6. bb.startAdvertising(param, function(ret, err) {
  7. if (ret && ret.status) {
  8. alert("请使用其他设备开始iBeacon扫描,您将看到当前设备模拟的UUID,Major&Minor:" + _uuid + "," + _major + "," + _minor);
  9. obj.innerHTML = "停止模拟";
  10. } else {
  11. alert(err.error);
  12. }
  13. });

可用性

iOS 7及以上系统,Android 5.0及以上系统

可提供的1.0.0及更高版本

stopAdvertising

停止模拟设备信号

stopAdvertising()

示例代码

  1. bb.stopAdvertising();

connectBeacon

连接设备,修改设备参数相关操作,需先执行本方法进行连接成功。

connectBeacon({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac地址。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. beacon: {
  4. uuid: //设备UUID,区域标识
  5. major: //设备主值,范围[0,65535]
  6. minor: //设备次值,范围[0,65535]
  7. rssi: //信号强度,和发射功率有关,范围约-20 ~ -100
  8. accuracy: //距离参考,由采样计算或rssi估算
  9. name: //设备名
  10. txPower: //设备发射功率
  11. txInterval: //设备发射频率
  12. mPower: //设备测量功率,1米处RSSI值,用于距离accuracy估算
  13. battery: //设备电量)
  14. temperature: //设备温度
  15. pMode: //设备是否加密
  16. version: //设备硬件版本
  17. firmware: //设备软件版本
  18. mac: //设备蓝牙mac地址
  19. broadcastMode://设备工作模式(0:仅iBeacon 2:实物网ID-取自uuid 3:实物网链接 4:0和2同时 5:0和3同时 6:2和3同时)
  20. eddystoneUrl://设备谷歌实物网链接
  21. }
  22. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:连接相关失败
  3. }

示例代码

  1. bb.connectBeacon({
  2. "mac": mac
  3. }, function(ret, err) {
  4. if(ret && ret.status) {
  5. //ret.beacon
  6. } else {
  7. alert(JSON.stringify(err));
  8. }
  9. }

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

disconnectBeacon

断开连接设备

disconnectBeacon({mac:xx})

params

mac:

  • 类型:字符串
  • 描述:设备mac(可选),留空断开所有连接设备。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. }

示例代码

  1. bb.disconnectBeacon({mac:'xx:xx:xx:xx:xx'});
  2. bb.disconnectBeacon();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

isBeaconConnected

设备是否处于连接中

isBeaconConnected({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //连接状态:true||false
  3. }

err:无

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

writeBeaconValues

连接成功后可用,写入设备广播数据、方式、配置设备发射频率、功率等

writeBeaconValues({mac:xx,…}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

uuid:

  • 类型:字符串
  • 描述:设备uuid

major:

  • 类型:字符串
  • 描述:设备major

minor:

  • 类型:字符串
  • 描述:设备minor

txInterval:

  • 类型:字符串
  • 描述:设备发射间隔,100毫秒~10秒

mPower:

  • 类型:字符串
  • 描述:设备测量功率,1米处rssi值,用于接收设备距离估算

pMode:

  • 类型:字符串
  • 描述:设备加密,需要APPKEY

txPower:

  • 类型:字符串
  • 描述:设备发射功率 -30 -20 -16 -12 -8 -4 0 4

batteryInterval:

  • 类型:字符串
  • 描述:设备电量检测间隔

temperatureInterval:

  • 类型:字符串
  • 描述:设备温度检测间隔

broadcastMode:

  • 类型:字符串
  • 描述:设备广播模式

eddystoneUrl:

  • 类型:字符串
  • 描述:谷歌实物网,国内无法使用

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:参见错误描述
  3. }

示例代码

  1. var param = {
  2. "mac": _mac,
  3. "uuid": _uuid,
  4. "major": _major,
  5. "minor": _minor,
  6. "name": _name,
  7. "txInterval": _txInterval,
  8. "mPower": _mPower,
  9. "pMode": _mode,
  10. "txPower": _txPower,
  11. "batteryInterval": _batteryInterval,
  12. "temperatureInterval": _temperatureInterval,
  13. "broadcastMode": _broadcastMode,
  14. "eddystoneUrl": _eddystoneUrl
  15. };
  16. //发起连接
  17. bb.connectBeacon({mac:_mac},function(r,e){
  18. if(r && r.status) {
  19. //写入参数
  20. bb.writeBeaconValues(param, function(ret, err) {
  21. //断开连接
  22. bb.disconnectBeacon(_mac);
  23. if(ret && ret.status) {api.toast({
  24. msg: '保存成功',
  25. duration: 2000,
  26. location: 'middle'
  27. });
  28. } else {
  29. alert(err.error);
  30. }
  31. });
  32. }
  33. }

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

sendBeaconValue

连接成功后可用,通过命令模式写入设备参数,基本参数修改效果同writeBeaconValues,并支持自定义扩展硬件的命令发送。
基本参数修改对应的消息ID:
0x00~0x3F:Beacon参数配置定义:
00重启 01版本 02温度电量 03写key 04读UUID 05写UUID 06读MM 07写MM 08读MPower 09写MPower
0A读功率 0B写功率 0C读模式 0D写模式 0E读名称 0F写名称 10读频率 11写频率 12读温度电量间隔 13写温电间隔 14读自定义广播
15写自定义广播 16读eddystoneUrl 17写eddystoneUrl 18开始/停止固件升级数据 19写入固件升级数据 20~3F内部扩展保留
0x40~0xFF:配合硬件SDK自定义传输使用

sendBeaconValue({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:参见错误描述
  3. }

示例代码

  1. //示例读取版本
  2. bb.sendBeaconValue({
  3. "mac": _mac,
  4. "value": "0102"
  5. }, function(ret, err) {
  6. if(ret.status) alert("示例:发送命令0102获取版本数据:" + ret.data + "(命令/数据格式:1byte标识+1byte当前命令总byte数+数据(<=18byte))");
  7. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

checkBeaconFirmwareUpdate

检测设备固件版本

checkBeaconFirmwareUpdate({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. update: true, //布尔型;true有更新,false无更新
  4. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:参见错误描述
  3. }

示例代码

  1. var param = {
  2. "mac": _mac
  3. };
  4. bb.checkBeaconFirmwareUpdate(param, function(ret, err) {
  5. if(ret && ret.status && ret.update) {
  6. bb.updateBeaconFirmwareWithProgress(param, function updateBack(ret, err){
  7. if(ret.progress == '100'){
  8. //升级完成
  9. }
  10. });
  11. } else {
  12. //error;
  13. }
  14. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

updateBeaconFirmwareWithProgress

更新设备固件

updateBeaconFirmwareWithProgress({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. progress:进度 [0,100]
  4. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:参见错误描述
  3. }

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

resetBeacon

重置设备参数,默认值:

参数名默认值
UUIDE2C56DB5-DFFB-48D2-B060-D0F5A71096E0
majormac后8位前4位
minormac后8位后4位
名称nameBrightBeacon
测量功率mPower-65
广播频率txInterval760ms
广播功率tx0dBm
设备加密pMode

resetBeacon({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. }

err:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. error:参见错误描述
  3. }

可用性

iOS系统,Android系统 可提供的1.0.0及更高版本