Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/petermetz/cordova-plugin-ibeacon

An iBeacon plugin for Phonegap / Cordova 3.x and upwards. Supports both iOS and Android (contributions are welcome)
https://github.com/petermetz/cordova-plugin-ibeacon
Last synced: 6 days ago
JSON representation
An iBeacon plugin for Phonegap / Cordova 3.x and upwards. Supports both iOS and Android (contributions are welcome)
Host: GitHub
URL: https://github.com/petermetz/cordova-plugin-ibeacon
Owner: petermetz
License: apache-2.0
Created: 2014-03-16T14:39:10.000Z (over 10 years ago)
Default Branch: v3.x
Last Pushed: 2024-02-12T09:51:25.000Z (10 months ago)
Last Synced: 2024-06-11T19:50:37.533Z (6 months ago)
Language: JavaScript
Homepage:
Size: 1.75 MB
Stars: 728
Watchers: 78
Forks: 372
Open Issues: 144
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project

awesome-IoT-hybrid - Cordova / Phonegap iBeacon plugin
awesome-beacon - Cordova iBeacon Plugin
README

        

## ![iBeacon Cordova Plugin](http://icons.iconarchive.com/icons/artua/mac/128/Bluetooth-icon.png) 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](https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/CLLocationManager/CLLocationManager.html) 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](https://github.com/petermetz/cordova-plugin-ibeacon/blob/master/www/LocationManager.js)'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](https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/CLLocationManager/CLLocationManager.html) 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(function(e) { console.error(e); })

	.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(function(e) { console.error(e); })

	.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(function(e) { console.error(e); })

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

```

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(console.error)

                .done();

        } else {

            console.log("Advertising not supported");

        }

    })

    .fail(function(e) { console.error(e); })

    .done();

```

##### 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)

```javascript

var uuid = cordova.plugins.locationManager.BeaconRegion.WILDCARD_UUID; //wildcard

var identifier = 'SomeIdentifier';

var major = undefined;

var minor = undefined;

var beaconRegion = new cordova.plugins.locationManager.BeaconRegion(identifier, uuid, major, minor);

var logToDom = function (message) {

	console.warn(message);

};

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

};

cordova.plugins.locationManager.setDelegate(delegate);

cordova.plugins.locationManager.startMonitoringForRegion(beaconRegion)

	.fail(function(e) { console.error(e); })

	.done();

```

##### 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](https://github.com/conventional-changelog/commitlint#what-is-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

* [Dart SDK](http://dartlang.org) installed on the path (Tested with: 1.2, 1.3, 1.3.3)

* [NodeJS](http://nodejs.org/)

* [NPM](https://www.npmjs.org/)

* [Cordova NPM package](https://www.npmjs.org/package/cordova) (Tested with: 3.4.0-0.1.3)

* [XCode](https://developer.apple.com/xcode/) (Tested with 5.0.2 and 6.0)

```

dart test/run_tests.dart

```

Executing the test runner will do the following:

* Generates a Cordova project

* Add the iOS platform

* Installs the iBeacon plugin from the local file-system.

* Launches XCode by opening the project.

### How to execute the tests - 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.