NOTE: THIS IS A WORK IN PROGRESS. IT'S NOT EVEN A BETA VERSION YET. EVERYTHING MAY CHANGE.
This is a Cordova/PhoneGap 3.x plugin for Android which allows interaction with Estimote iBeacons. This plugin is just a wrapper around Estimote Android SDK.
This plugin allows for:
- beacon ranging: Scan beacons and optionally filter them by their values.
- beacon monitoring: Monitor regions for those devices that have entered/exited a region.
- beacon characteristics reading (proximity UUID, major & minor values, etc.).
- Apache Cordova/Adobe PhoneGap 3.x.
- Android SDK.
- Device with Android 4.3+ and Bluetooth 4.0+ (a.k.a. Bluetooth Low Energy or BLE).
In order to add this plugin into your project:
Using Cordova:
$ cordova plugin add https://github.com/mdc-ux-team/estimote-beacons-phonegap-plugin-for-android.git
Using PhoneGap:
$ phonegap local plugin add https://github.com/mdc-ux-team/estimote-beacons-phonegap-plugin-for-android.git
In your www/js/index.js
file:
var myInterval;
function startRangingBeaconsInRegionCallback() {
console.log('Start ranging beacons...');
// Every now and then get the list of beacons in range
myInterval = setInterval(function() {
EstimoteBeacons.getBeacons(function(beacons) {
console.log('Getting beacons...');
for(var i = 0, l = beacons.length; i < l; i++) {
var beacon = beacons[i];
// beacon contains major, minor, rssi, macAddress, measuredPower, etc.
console.log('beacon:', beacon);
}
...
});
}, 3000);
}
var app = {
bindEvents: function() {
document.addEventListener('deviceready', this.onDeviceReady);
},
initialize: function() {
this.bindEvents();
},
onDeviceReady: function() {
document.removeEventListener('deviceready', app.onDeviceReady);
if(!EstimoteBeacons) return;
document.addEventListener('pause', app.onPause);
document.addEventListener('resume', app.onResume);
EstimoteBeacons.startRangingBeaconsInRegion(startRangingBeaconsInRegionCallback);
},
onPause: function() {
EstimoteBeacons.stopRangingBeaconsInRegion(function() {
console.log('Stop ranging beacons...');
});
clearInterval(myInterval);
},
onResume: function() {
EstimoteBeacons.startRangingBeaconsInRegion(startRangingBeaconsInRegionCallback);
}
};
EstimoteBeacons.startRangingBeaconsInRegion(successCallback)
Starts ranging for beacons.
EstimoteBeacons.stopRangingBeaconsInRegion(successCallback)
Stops ranging for beacons.
EstimoteBeacons.startMonitoringBeaconsInRegion(successCallback)
Starts monitoring region.
EstimoteBeacons.stopMonitoringBeaconsInRegion(successCallback)
Stops monitoring region.
EstimoteBeacons.getBeacons(successCallback)
Returns latest list of beacons found by startRangingBeaconsInRegion
. You have to call this method periodically to be up to date with latest results.
EstimoteBeacons.isBleSupported(successCallback, errorCallback)
Determines whether BLE is supported or not.
EstimoteBeacons.isBluetoothEnabled(successCallback, errorCallback)
Determines whether Bluetooth is enabled or not.
- Sometimes this plugin stops working because of an error: "Bluetooth share has stopped". This is an Android bug. For more information about this bug read Estimote Android SDK FAQ section. When this error appears, it may be necessary to factory reset your device. NOTE: BACKUP YOUR DATA AND APPS BEFORE FACTORY RESET YOUR DEVICE.
- For which Android devices could I develop a hybrid app using this plugin?
These could be some of them:
- Samsung Galaxy S3
- Samsung Galaxy S4
- Samsung Galaxy S4 Mini
- Samsung Galaxy S5
- Samsung Galaxy Note 2
- Samsung Galaxy Note 3
- Google Nexus 4
- Google Nexus 5
- Google Nexus 7
- Is there an app to check if my Android device supports BLE?
BLE Checker. We have tested this app in a couple of Android devices and it seems to work fine.
- Is there an Estimote iBeacons Cordova/PhoneGap plugin for iOS?
Yes. Take a look at the kdzwinel/phonegap-estimotebeacons project being developed by Konrad Dzwinel.
- How can I edit the value of the Major/Minor property of a beacon?
- Install Estimote app.
- Click Beacons.
- Click any of the beacons within the radar.
- Click Major/Minor.
- Enter the new value for Major/Minor and click Save Major/Minor.
- Improved documentation.
- Added isBluetoothEnabled and isBleSupported methods.
- Added JavaDoc and JSDoc comments.
- Improved Java and JavaScript code.
- Updated plugin id and Java namespace.
- First implementation.