-
Notifications
You must be signed in to change notification settings - Fork 82
iBeacon Bluetooth Services
This sdk documentation is deprecated and will not be updated. Check out our new docs at https://sdk.buildfire.com/docs/ibeacon-bluetooth/
iBeacon is a protocol developed by Apple and introduced at the Apple Worldwide Developers Conference in 2013.[1] Various vendors have since made iBeacon-compatible hardware transmitters - typically called beacons - a class of Bluetooth low energy (BLE) devices that broadcast their identifier to nearby portable electronic devices. The technology enables smartphones, tablets, and other devices to perform actions when in close proximity to an iBeacon ref: https://en.wikipedia.org/wiki/IBeacon
Use this service on the widget side of your plugins to monitor and range beacons
- From the Widget
<script src="../../../scripts/buildfire/services/bluetooth/iBeacon.js"></script>
- in
plugin.json
addiBeacon
in yourfeature
array"features" : [{"name" : "iBeacon"}]
none. iBeacon
is a singleton
namespace: buildfire.services.bluetooth.iBeacon
-
createBeaconRegion (uuid,identifier,minor,major)
: use this factory method to create a beacon region. Note: if you specify only auuid
and not themajor
orminor
then it will scan all majors and minors-
uuid
: the universally unique id. Beacons are pre-set by the manufacturer with auuid
some provide an interface to change theuuid
so beacons may be grouped together and vary based onmajor
andminor
-
-
startMonitoring function (beaconRegion, callback)
: used to tell the OS to begin listening for this region of beacons. When you enter or exit a region events will trigger such asonRegionEntered
andonRegionExited
. The OS will wake up the app in the background if it's killed and trigger these events. the app will be alive only for a few seconds.-
beaconRegion
: beacon region created bycreateBeaconRegion
-
callback(error)
: callback function called when command is completed.
-
-
stopMonitoring function (beaconRegion, callback)
: use this method to tell the OS to stop listening for this region of beacons.-
beaconRegion
: beacon region created bycreateBeaconRegion
-
callback(error)
: callback function called when command is completed.
-
-
startRanging function(beaconRegion, callback)
: begin aggressively ranging nearby beacon. This will help you determine the distance of each beacon detected. Updates will trigger theonRangingUpdate
event.-
beaconRegion
: beacon region created bycreateBeaconRegion
-
callback(error)
: callback function called when command is completed.
-
-
stopRanging function(beaconRegion, callback)
: stop ranging beacons in the region provided. Make sure you only range when needed since it will drain the battery if you don't.-
beaconRegion
: beacon region created bycreateBeaconRegion
-
callback(error)
: callback function called when command is completed.
-
-
onRegionEntered: function(beaconRegion)
: gets called when entering a new beacon region matching a region you are monitoring-
beaconRegion
: object containing the region detected
-
beaconRegion:
{
"region":
{
"uuid" : "id provided to monitor"
, "identifier" : "identifier provided to monitor"
, "major" : "major provided to monitor"
, "minor" : "minor provided to monitor"
}
}
-
onRegionExited: function(beaconRegion)
: gets called when exiting a new beacon region that's being monitored.-
beaconRegion
: object containing the region detected
-
beaconRegion:
{
"region":
{
"uuid" : "id provided to monitor"
, "identifier" : "identifier provided to monitor"
, "major" : "major provided to monitor"
, "minor" : "minor provided to monitor"
}
}
-
onRangingUpdate: function(beaconRegion)
: gets called when an update on beacon region is detected.-
beaconRegion
: object containing the region detected and an array of beacons detected in that region
-
beaconRegion:
{
"region":
{
"uuid" : "id provided to monitor"
, "identifier" : "identifier provided to monitor"
, "major" : "major provided to monitor"
, "minor" : "minor provided to monitor"
}
,"beacons":[
{"minor":42532,"rssi":0,"major":63878,"proximity":"ProximityUnknown","accuracy":-1,"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D"}
,{"minor":20151,"rssi":-45,"major":10068,"proximity":"ProximityImmediate","accuracy":0.02,"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D"}
,{"minor":807,"rssi":-81,"major":34751,"proximity":"ProximityFar","accuracy":2.33,"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D"}]}
}
- Proximity Values:
["ProximityUnknown", "ProximityImmediate", "ProximityNear", "ProximityFar"]
- Since this only works on a mobile device, iBeacons will only function on the widget side of your plugins
- There is a limit from the OS on how many
UUID
s you can monitor. However, you can have thousands ofmajor
andminor
ranges - Monitoring a beacon region will trigger events even if your app is killed (unlike ranging). The app will wake up in the background and only live for a few seconds before its killed again
- Since Monitoring is always scanning, it does this very passively. For example, it will check only every few seconds (will vary) to see if you have entered a region. It will wait 30 seconds (or so) outside a region to be sure you have left before triggering the exited event