Estimote iBeacons Cordova/PhoneGap Plugin for Android

Overview

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 (Mac Address, RSSI, Major & Minor values, etc.).

Requirements

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

Installation

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

Usage

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

Estimote Beacons Cordova/PhoneGap Sample App

Available Methods

startRangingBeaconsInRegion

EstimoteBeacons.startRangingBeaconsInRegion(successCallback) Starts ranging for beacons.

stopRangingBeaconsInRegion

EstimoteBeacons.stopRangingBeaconsInRegion(successCallback) Stops ranging for beacons.

startMonitoringBeaconsInRegion

EstimoteBeacons.startMonitoringBeaconsInRegion(successCallback) Starts monitoring region.

stopMonitoringBeaconsInRegion

EstimoteBeacons.stopMonitoringBeaconsInRegion(successCallback) Stops monitoring region.

getBeacons

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.

isBleSupported

EstimoteBeacons.isBleSupported(successCallback, errorCallback) Determines whether BLE is supported or not.

isBluetoothEnabled

EstimoteBeacons.isBluetoothEnabled(successCallback, errorCallback) Determines whether Bluetooth is enabled or not.

Known Issues

• 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.

FAQ

1. 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

2. Is there an app to check if my Android device supports BLE?

BLE Checker.

3. 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.

4. How can I edit the value of the Major/Minor property of a beacon?

1. Install Estimote app.
2. Click Beacons.
3. Click any of the beacons displayed in the radar.
4. Click Major/Minor.
5. Enter the new value for Major/Minor and click Save Major/Minor.

Changelog

0.0.4

• Minor Java code improvements.
• Improved Bluetooth detection.
• Updated Estimote SDK to version 0.4.2.

0.0.3

• Improved documentation.
• Added isBluetoothEnabled and isBleSupported methods.

0.0.2

• Added JavaDoc and JSDoc comments.
• Improved Java and JavaScript code.
• Updated plugin id and Java namespace.

0.0.1

• First implementation.

References

• Apache Cordova Documentation.
• Adobe PhoneGap Documentation.

License

MIT