README.md

Estimote iBeacons Cordova/PhoneGap Plugin for Android

NOTE: THIS IS A WORK IN PROGRESS. IT'S NOT EVEN A BETA VERSION YET. EVERYTHING MAY CHANGE.

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 (proximity UUID, major & minor values, etc.).

Requirements

• Apache Cordova/Adobe PhoneGap 3.x.
• Android SDK.
• Device with Android 4.3 or above and Bluetooth 4.0 or above (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...');
  
  // Every now and then get the list of beacons in range
  myInterval = setInterval(function() {
    EstimoteBeacons.getBeacons(function(data) {
      // data contains: proximityUUID, major, minor, rssi, macAddress and measuredPower
      console.log('Getting beacons...');
      ...
    });
  }, 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...');
    });
    clearInterval(myInterval);
  },
  
  onResume: function() {
    EstimoteBeacons.startRangingBeaconsInRegion(startRangingBeaconsInRegionCallback);
  }
};

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.

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 bullet 2 within the FAQ section of Estimote Android SDK. 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

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

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

1. How can I edit the value of the Major/Minor property of a beacon?
2. Install Estimote app.
3. Click Beacons.
4. Click any of the beacons within the radar.
5. Click Major/Minor.
6. Enter the new value for Major/Minor and click Save Major/Minor.

Changelog

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

• Adobe PhoneGap Documentation.
• Apache Cordova Documentation.

License

MIT