DOCSEARCHbyAlgolia
Submit Docs

cordova-plugin-ibeacon

repository·v3.x·Indexed 20 days ago

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

A Cordova/PhoneGap plugin (version 3.8.1) for interacting with iBeacons, enabling mobile applications to detect and interact with Bluetooth Low Energy (BLE) beacons. The API is modeled after Apple's CLLocationManager and provides functionality for monitoring and ranging beacons via the cordova.plugins.locationManager namespace using a Promise-based async pattern and a Delegate pattern for event handling.

Tokens
2.3K
Snippets
7
Records
11
Agent score
23%

What's inside cordova-plugin-ibeacon

  1. Core concepts of the LocationManager API

    v3.x

    The plugin's API is modeled after Apple's CLLocationManager.

    Key architectural details:

    • Namespace: Since version 2, the plugin no longer pollutes the global namespace. All functionality is accessed via cordova.plugins.locationManager.
    • Async Pattern: Since version 2, the API is based on Promises rather than callbacks. Methods typically support .done(), .fail(), and .then().
    • Delegate Pattern: To handle asynchronous events (like discovering a beacon or state changes), you must create a cordova.plugins.locationManager.Delegate instance and register it using cordova.plugins.locationManager.setDelegate(delegate).
    • Data Objects: Use cordova.plugins.locationManager.BeaconRegion to create Data Transfer Objects (DTOs) representing the beacons you want to monitor or range.

  2. Range iBeacons (iOS and Android)

    v3.x

    Ranging provides continuous updates on the proximity of beacons within a region. The implementation is identical to Monitoring, but uses startRangingBeaconsInRegion(beaconRegion) and stopRangingBeaconsInRegion(beaconRegion).

    // ... setup delegate and beaconRegion as shown in monitoring ...

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

// To stop:
// cordova.plugins.locationManager.stopRangingBeaconsInRegion(beaconRegion)

  3. Configure iOS background permissions for managed services

    v3.x

    When using managed services like Phonegap Build or Ionic Cloud, you may need to manually ensure that background location modes are enabled in your iOS configuration.

    You can use the edit-config tag in your config.xml to merge the location string into the UIBackgroundModes array of your Info.plist file.

    <edit-config file="*-Info.plist" target="UIBackgroundModes" mode="merge">
    <array>
        <string>location</string>
    </array>
</edit-config>

  5. Monitor iBeacons (iOS and Android)

    v3.x

    Monitoring allows you to detect when a device enters or exits a specific beacon region.

    Steps to implement:

    1. Create a BeaconRegion.
    2. Create and configure a Delegate to handle events like didDetermineStateForRegion, didStartMonitoringForRegion, and didRangeBeaconsInRegion.
    3. Register the delegate with cordova.plugins.locationManager.setDelegate(delegate).
    4. (iOS 8+) Request authorization using requestWhenInUseAuthorization() or requestAlwaysAuthorization().
    5. Call startMonitoringForRegion(beaconRegion).

    To stop monitoring, call stopMonitoringForRegion(beaconRegion).

    var delegate = new cordova.plugins.locationManager.Delegate();

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

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

delegate.didRangeBeaconsInRegion = function (pluginResult) {
    console.log('didRangeBeaconsInRegion:', 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(); 

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

  6. How to test the plugin on iOS/Safari without the Dart SDK

    v3.x

    To manually verify plugin functionality on an iOS device or simulator without a full development environment, follow these steps:

    1. Open an application that has the cordova-plugin-ibeacon installed in Xcode.
    2. Install and run the app on a physical iOS device or a simulator.
    3. Open Safari on the device (or via the Safari Web Inspector on macOS connected to the device).
    4. Open the developer tools window (Web Inspector).
    5. Copy the code from the plugin's example files and paste it directly into the JavaScript console. The code should execute without errors.

  7. Customize AltBeacon scan frequency on Android

    v3.x

    To control how frequently the AltBeacon library scans for proximity devices (beacons) on Android, add a specific preference to your config.xml.

    Use the com.unarin.cordova.beacon.android.altbeacon.ForegroundBetweenScanPeriod preference to set the delay in milliseconds between foreground scans. The default value is 0.

    <preference name="com.unarin.cordova.beacon.android.altbeacon.ForegroundBetweenScanPeriod" value="5000" />

  8. Configure Android Bluetooth and ARMA Filter

    v3.x

    The following preferences can be set in your config.xml to modify Android-specific behavior:

    • Enable ARMA Filter: Enables an ARMA filter for distance calculations, which weighs recent measurements higher than older ones.
      • Key: com.unarin.cordova.beacon.android.altbeacon.EnableArmaFilter (set to true to enable).
    • Disable Automatic Bluetooth Permission Request: By default, the plugin requests Bluetooth permissions on startup. Set this to false to handle permissions manually.
      • Key: com.unarin.cordova.beacon.android.altbeacon.RequestBtPermission (set to false to disable).
    <!-- Enable ARMA filter -->
<preference name="com.unarin.cordova.beacon.android.altbeacon.EnableArmaFilter" value="true" />

<!-- Disable automatic Bluetooth permission request -->
<preference name="com.unarin.cordova.beacon.android.altbeacon.RequestBtPermission" value="false" />

  10. Create BeaconRegion DTOs

    v3.x

    To interact with specific beacons, you must create a BeaconRegion object. This object requires a uuid and an identifier. major and minor values are optional and default to wildcards if omitted.

    /**
 * 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;   
}