Readme

The Logical Labs Beacons module allows Titanium apps to communicate with beacons.

Usage

To access this module from JavaScript, you would do the following:

var Beacons = require("com.logicallabs.beacons");

The Beacons variable is a reference to the Module object.

The next step is to wait for the moduleReady event.

Use the createBeaconRegion function to create beacon region objects:

 var beaconRegion = Beacons.createBeaconRegion({
                            UUID: uuid,
                            identifier: '#' + idCounter
                    });

This object then can be passed to the startRegionMonitoring function to start monitoring:

Beacons.startRegionMonitoring({
    beaconRegion: region
});

This will result in enteredRegion, exitedRegion, and regionStateUpdated events.

You will typically want to call the requestRegionState function right after you call startRegionMonitoring to get an update of the current region state immediately. Otherwise you might only receive the first update when the state of a region changes. This can be a problem if the user is in the region you are interested in at the time the app starts.

Once the user enters a region, the startRangingBeacons function can be used to get periodic updates about the beacons in range:

Beacons.addEventListener('regionStateUpdated', function(e) {
    switch(e.state) {
        case Beacons.REGION_STATE_INSIDE:
            Beacons.startRangingBeacons({
                beaconRegion: e.region
            });
            break;
        case Beacons.REGION_STATE_OUTSIDE:
            Beacons.stopRangingBeacons({
                beaconRegion: e.region
            });
            break;
    }
});

This will result in rangedBeacons events.

Use the stopRangingBeacons and stopRegionMonitoring functions to stop ranging and monitoring, respectively.

Background operation

If the app started beacon region monitoring, it will receive enteredRegion, exitedRegion, and regionStateUpdated events while in the background. The iBeacons example demonstrates how to display a local notification to the user when this happens.

Restarting into the background

Starting with iOS7, beacon related events can trigger the app to be restarted into (!) the background after it was stopped (removed from memory) by iOS to free up resources. Starting with iOS7.1, beacon related events can restart the app into the background even if the user explicitly removed the app from the active app list.

In order to take advantage of this feature, simply start monitoring a beacon region.

When the app restarts due to a beacon related event, the wasLocationLaunch property will be true. Use the retrieveMonitoredRegions function to retrieve the beacon regions that are already being monitored.

Beacon Usage Permissions

Starting with iOS 8, the authorization model related to location services, and thus beacons, has changed. If the app wants to use beacon related functionality, it now needs to explicitly call either the BluetoothLEModule/requestWhenInUseAuthorization:method or the BluetoothLEModule/requestAlwaysAuthorization:method function, and specify either the NSLocationAlwaysUsageDescription or the NSLocationWhenInUseUsageDescription Info.plist entry in tiapp.xml:

<ios>
   <plist>
       <dict>
           <key>NSLocationAlwaysUsageDescription</key>
           <string>
                Please allow access to enable beacon monitoring!
            </string>
           <key>NSLocationWhenInUseUsageDescription</key>
           <string>
                Please allow access to enable beacon ranging!
            </string>
       </dict>
   </plist>
</ios>

When the app calls the BluetoothLEModule/requestWhenInUseAuthorization:method or the BluetoothLEModule/requestAlwaysAuthorization:method function, the user is presented with a dialog that requests permission. The string you associated with the NSLocationAlwaysUsageDescription or the NSLocationWhenInUseUsageDescription key will be displayed to the user in this dialog.

The difference between "when-in-use" and "always" authorization is significant: "when-in-use" means that the app can only access these services while it's running in the foreground, and it cannot request region monitoring even then. Therefore many apps that use beacons will need "always" authorization.

However, Apple discourages the use of "always" authorization. To quote: "Requesting “Always” authorization is discouraged because of the potential negative impacts to user privacy. You should request this level of authorization only when doing so offers a genuine benefit to the user."

Issues and Limitations

None.

Change Log

Version 1.2.0

Initial release

Version 1.2.4

Documentation improvements
Sample app improvements
Added requestRegionState function.

Version 1.2.5

Added restoredPeripheralManagerIdentifiers property.
Added retrieveMonitoredRegions function and retrievedMonitoredRegions event.
Added wasLocationLaunch property.

Version 1.2.6

Version 1.2.7

Introduced the requestWhenInUseAuthorization and requestAlwaysAuthorization functions.
Updated Readme with Beacon Usage Permissions section.
Updated sample app.

Author

Zsombor Papp, Logical Labs

titanium@logicallabs.com

License

Logical Labs Commercial License

Logical Labs Beacons Module for iOS

APIs