brightBeacon

registerAppKey stopRanging stopMonitoring isMonitorRegion startAdvertising connectBeacon isBeaconConnected sendBeaconValue updateBeaconFirmwareWithProgress

概述

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))

key：

callback(ret, err)

ret：

  • 类型：JSON对象
  • 内部字段：

err：

  • 类型：JSON对象
  • 内部字段：
  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:

  • 类型：字符串

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) {
  22.                         } else {
  23.                             alert(err1.error);
  24.                         }
  25.                     });
  26.                 }
  27.             } else {
  28.                 api.alert({
  29.                     title: '错误',
  30.                     msg: err.error,
  31.                 }, function(ret, err) {
  33.                 });
  34.             }
  35.         });

补充说明

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
  6.         }, function(ret, err) {
  7.             alert(JSON.stringify(ret));
  8.             alert(JSON.stringify(err));
  9.         });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

monitorRegions

获取当前监听中的区域

monitorRegions(callback(ret))

callback(ret)

  • 类型：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格式生成）

    示例代码

可用性

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.             battery:        //设备电量）
  13.             temperature:    //设备温度
  14.             pMode:            //设备是否加密
  15.             version:        //设备硬件版本
  16.             firmware:        //设备软件版本
  17.             mac:            //设备蓝牙mac地址
  18.             broadcastMode://设备工作模式（0：仅iBeacon 2：实物网ID-取自uuid 3：实物网链接 4：0和2同时 5：0和3同时 6：2和3同时）
  19.             eddystoneUrl://设备谷歌实物网链接
  20.   }
  21. }

err：

  • 类型：JSON对象
  • 内部字段：
  1. {
  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.     或
  3.     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. }

可用性

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对象
  • 内部字段：

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

重置设备参数，默认值：

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

params

mac：

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

ret：

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

err：

  • 类型：JSON对象
  • 内部字段：
  1. {

可用性

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