cordova-plugin-ibeacon

Cordova / Phonegap iBeacon plugin

Features

Features available on both Android and iOS

• Ranging
• Monitoring

Features exclusive to iOS

• Region Monitoring (or geo fencing), works in all app states.
• Advertising device as an iBeacon

Features exclusive to Android

• ARMA filter for distance calculations
• Disable request for bluetooth permissions

Installation

cordova plugin add https://github.com/petermetz/cordova-plugin-ibeacon.git

Usage

The plugin's API closely mimics the one exposed through the CLLocationManager introduced in iOS 7.

Since version 2, the main IBeacon facade of the DOM is called LocationManager and it's API is based on promises instead of callbacks. Another important change of version 2 is that it no longer pollutes the global namespace, instead all the model classes and utilities are accessible through the cordova.plugins.locationManager reference chain.

Since version 3.2 the Klass dependency has been removed and therefore means creation of the delegate has changed.

iOS 8 Permissions

On iOS 8, you have to request permissions from the user of your app explicitly. You can do this through the plugin's API. See the LocationManager's related methods: requestWhenInUseAuthorization and requestAlwaysAuthorization for further details.

In order to use Advertising (e.g startAdvertising), the iOS-Capability "Location updates" is required. (set in Xcode -> [your Target] -> Capabilities -> Background Modes -> Location updates)

Standard CLLocationManager functions

Creating BeaconRegion DTOs

…

Start monitoring a single iBeacon

…

Stop monitoring a single iBeacon

var uuid = '00000000-0000-0000-0000-000000000000';
var identifier = 'beaconOnTheMacBooksShelf';
var minor = 1000;
var major = 5;
var beaconRegion = new cordova.plugins.locationManager.BeaconRegion(identifier, uuid, major, minor);

cordova.plugins.locationManager.stopMonitoringForRegion(beaconRegion)
	.fail(function(e) { console.error(e); })
	.done();

Start ranging a single iBeacon

…

Stop ranging a single iBeacon

var uuid = '00000000-0000-0000-0000-000000000000';
var identifier = 'beaconOnTheMacBooksShelf';
var minor = 1000;
var major = 5;
var beaconRegion = new cordova.plugins.locationManager.BeaconRegion(identifier, uuid, major, minor);

cordova.plugins.locationManager.stopRangingBeaconsInRegion(beaconRegion)
	.fail(function(e) { console.error(e); })
	.done();

Determine if advertising is supported (iOS is supported, Android is not yet)

cordova.plugins.locationManager.isAdvertisingAvailable()
    .then(function(isSupported){
        console.log("isSupported: " + isSupported);
    })
    .fail(function(e) { console.error(e); })
    .done();

Determine if advertising is currently turned on (iOS only)

cordova.plugins.locationManager.isAdvertising()
    .then(function(isAdvertising){
        console.log("isAdvertising: " + isAdvertising);
    })
    .fail(function(e) { console.error(e); })
    .done();

Start advertising device as an iBeacon (iOS only)

…

Stopping the advertising (iOS only)

cordova.plugins.locationManager.stopAdvertising()
    .fail(function(e) { console.error(e); })
    .done();

Enable/Disable BlueTooth (Android only)

cordova.plugins.locationManager.isBluetoothEnabled()
    .then(function(isEnabled){
        console.log("isEnabled: " + isEnabled);
        if (isEnabled) {
            cordova.plugins.locationManager.disableBluetooth();
        } else {
            cordova.plugins.locationManager.enableBluetooth();        
        }
    })
    .fail(function(e) { console.error(e); })
    .done();

Specify wildcard UUID (Android only)

…

Enable ARMA filter for distance calculations (Android only)

The underlying library uses the moving average to calculate distance by default, but an ARMA filter can be enabled which will weigh more recent measurements higher than older measurements. It can be enabled by adding the following preference to your config.xml file:

#### Disable request for bluetooth permission
By default, this library requests the user for bluetooth permissions when the app starts. If you would like to request permission in a different way or at a different time, set the following preference in your `config.xml` file.

Contributions

Contributions are welcome at all times, please make sure that the tests are running without errors before submitting a pull request. The current development branch that you should submit your pull requests against is "v3.x" branch.

This project uses commitlint, please ensure all commit messages pass commitlint before submitting a pull request.

Release checklist

• CHANGELOG.md list meaningful changes since last release, use the format of git log --pretty=oneline --abbrev-commit
• package.json bump the version
• plugin.xml bump the version
• Publish to both npm packages (due to historical reasons)
  • $ npm publish (this publishes under com.unarin.cordova.beacon in npm)
  • Edit name property in the package.json file from com.unarin.cordova.beacon to cordova-plugin-ibeacon (do not commit the change)
  • $ npm publish again to publish under the legacy package name as well
  • revert the change you just did in package.json

How to execute the tests - OS X

Prerequisites Of The Test Runner

• NodeJS
• npm
• Cordova npm package (Tested with: 3.4.0-0.1.3)
• XCode (Tested with 5.0.2 and 6.0)

How to execute the tests on iOS/Safari - Without the Dart SDK

• Open an app which has Cordova iBeacon plugin installed in XCode
• Install it onto a device or simulator
• Open Safari
• Go to the dev tools window
• Paste the code from the examples into the javascript console, it should run without any errors.