Home

Awesome

<!--- license: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->

iBeacon Cordova Plugin Cordova / Phonegap iBeacon plugin

Features

Features available on both Android and iOS

Features exclusive to iOS

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.

Standard CLLocationManager functions

Creating BeaconRegion DTOs
/**
 * Function that creates a BeaconRegion data transfer object.
 * 
 * @throws Error if the BeaconRegion parameters are not valid.
 */
function createBeacon() {

    var uuid = '00000000-0000-0000-0000-000000000000'; // mandatory
    var identifier = 'beaconAtTheMacBooks'; // mandatory
    var minor = 1000; // optional, defaults to wildcard if left empty
    var major = 5; // optional, defaults to wildcard if left empty

    // throws an error if the parameters are not valid
    var beaconRegion = new cordova.plugins.locationManager.BeaconRegion(identifier, uuid, major, minor);
   
    return beaconRegion;   
}
Start monitoring a single iBeacon
var logToDom = function (message) {
	var e = document.createElement('label');
	e.innerText = message;

	var br = document.createElement('br');
	var br2 = document.createElement('br');
	document.body.appendChild(e);
	document.body.appendChild(br);
	document.body.appendChild(br2);
	
	window.scrollTo(0, window.document.height);
};

var delegate = new cordova.plugins.locationManager.Delegate();
	
delegate.didDetermineStateForRegion = function (pluginResult) {

    logToDom('[DOM] didDetermineStateForRegion: ' + JSON.stringify(pluginResult));

    cordova.plugins.locationManager.appendToDeviceLog('[DOM] didDetermineStateForRegion: '
        + JSON.stringify(pluginResult));
};

delegate.didStartMonitoringForRegion = function (pluginResult) {
    console.log('didStartMonitoringForRegion:', pluginResult);

    logToDom('didStartMonitoringForRegion:' + JSON.stringify(pluginResult));
};

delegate.didRangeBeaconsInRegion = function (pluginResult) {
    logToDom('[DOM] didRangeBeaconsInRegion: ' + JSON.stringify(pluginResult));
};

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.setDelegate(delegate);

// required in iOS 8+
cordova.plugins.locationManager.requestWhenInUseAuthorization(); 
// or cordova.plugins.locationManager.requestAlwaysAuthorization()

cordova.plugins.locationManager.startMonitoringForRegion(beaconRegion)
	.fail(console.error)
	.done();
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(console.error)
	.done();
Start ranging a single iBeacon
var logToDom = function (message) {
	var e = document.createElement('label');
	e.innerText = message;

	var br = document.createElement('br');
	var br2 = document.createElement('br');
	document.body.appendChild(e);
	document.body.appendChild(br);
	document.body.appendChild(br2);
	
	window.scrollTo(0, window.document.height);
};

var delegate = new cordova.plugins.locationManager.Delegate();
	
delegate.didDetermineStateForRegion = function (pluginResult) {

    logToDom('[DOM] didDetermineStateForRegion: ' + JSON.stringify(pluginResult));

    cordova.plugins.locationManager.appendToDeviceLog('[DOM] didDetermineStateForRegion: '
        + JSON.stringify(pluginResult));
};

delegate.didStartMonitoringForRegion = function (pluginResult) {
    console.log('didStartMonitoringForRegion:', pluginResult);

    logToDom('didStartMonitoringForRegion:' + JSON.stringify(pluginResult));
};

delegate.didRangeBeaconsInRegion = function (pluginResult) {
    logToDom('[DOM] didRangeBeaconsInRegion: ' + JSON.stringify(pluginResult));
};



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.setDelegate(delegate);

// required in iOS 8+
cordova.plugins.locationManager.requestWhenInUseAuthorization(); 
// or cordova.plugins.locationManager.requestAlwaysAuthorization()

cordova.plugins.locationManager.startRangingBeaconsInRegion(beaconRegion)
	.fail(console.error)
	.done();
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(console.error)
	.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(console.error)
    .done();
Determine if advertising is currently turned on (iOS only)
cordova.plugins.locationManager.isAdvertising()
    .then(function(isAdvertising){
        console.log("isAdvertising: " + isAdvertising);
    })
    .fail(console.error)
    .done();
Start advertising device as an iBeacon (iOS only)
var uuid = '00000000-0000-0000-0000-000000000000';
var identifier = 'advertisedBeacon';
var minor = 2000;
var major = 5;
var beaconRegion = new cordova.plugins.locationManager.BeaconRegion(identifier, uuid, major, minor);

// The Delegate is optional
var delegate = new cordova.plugins.locationManager.Delegate();

// Event when advertising starts (there may be a short delay after the request)
// The property 'region' provides details of the broadcasting Beacon
delegate.peripheralManagerDidStartAdvertising = function(pluginResult) {
    console.log('peripheralManagerDidStartAdvertising: '+ JSON.stringify(pluginResult.region));
};
// Event when bluetooth transmission state changes 
// If 'state' is not set to BluetoothManagerStatePoweredOn when advertising cannot start
delegate.peripheralManagerDidUpdateState = function(pluginResult) {
    console.log('peripheralManagerDidUpdateState: '+ pluginResult.state);
};

cordova.plugins.locationManager.setDelegate(delegate);

// Verify the platform supports transmitting as a beacon
cordova.plugins.locationManager.isAdvertisingAvailable()
    .then(function(isSupported){

        if (isSupported) {
            cordova.plugins.locationManager.startAdvertising(beaconRegion)
                .fail(conole.error)
                .done();
        } else {
            console.log("Advertising not supported");
        }
    })
    .fail(console.error)
    .done();
Stopping the advertising (iOS only)
cordova.plugins.locationManager.stopAdvertising()
    .fail(console.error)
    .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(console.error)
    .done();

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.

How to execute the tests - OS X

Prerequisites Of The Test Runner

dart test/run_tests.dart

Executing the test runner will do the following:

How to execute the tests - Without the Dart SDK