Beacon API

The Beacon API helps you work with iBeacons. iBeacons are devices that transmit signals using Bluetooth low-energy wireless technology, and allow you to create and monitor beacons that advertise certain identifying information. Beacon Region is a region defined by a device’s proximity to Bluetooth Beacons.

The Beacon API uses the com.kony.Beacon object and the com.kony.BeaconManager namespaces and the following API elements

com.kony.Beacon Methods

Method	Description
`getAccuracy`	The accuracy of the proximity value, measured in meters from the beacon.
`getMajor`	The most significant value in the beacon. A major value, which is a number that can be used to group related beacons that have the same proximity UUID.
`getMinor`	The least significant value in the beacon. A minor value, which is a number that differentiates beacons with the same proximity UUID and major value.
`getProximity`	The proximity value gives a general sense of the relative distance to the beacon. Use it to quickly identify beacons that are nearer to the user rather than farther away.
`getProximityUUIDString`	The proximity UUID (string representation) of the beacon.
`getrssi`	The received signal strength of the beacon, measured in decibels.

com.kony.BeaconManager Methods

Method	Description
`authorizationStatus`	Helps you know the authorization status of the location services for the application.
`getMonitoredRegions`	Gets the Beacon Regions that are currently being monitored.
`getRangedRegions`	Gets the the BeaconRegion objects that are currently being ranged.
`isMonitoringAvailableForBeaconRegions`	Determine whether monitoring is available for the beacon regions.
`isRangingAvailableForBeaconRegions`	Determine whether ranging is available for the beacon regions.
`requestStateForRegion`	Determine the state of the current device relative to the beacon region.
`setAuthorizationStatusChangedCallback`	Sets the callback function that retrieves the authorization status changes.
`setMonitoringStartedForRegionCallback`	Sets the monitoring started for region callback.
`startMonitoringBeaconRegion`	Start monitoring for the specified Beacon Region.
`startRangingBeaconsInRegion`	Starts ranging beacons in a specified beacon region.
`stopMonitoringBeaconsRegion`	Stops monitoring a specified beacon region.
`stopRangingBeaconsInRegion`	Stop ranging beacons in a specified Beacon Region.

Prerequisites

To use Beacon FFI APIs, you need iOS 7 or later, Bluetooth turned on, and a compatible iOS device:

Xcode 5.0 or later
iPhone 4s or later
iPad (3rd generation) or later
iPad mini or later
iPod touch (5th generation) or later

The following classes are available in Beacon FFI:

How-to Sections

This overview provides the how-tos that demonstrate the use of the Beacon API in the following topics.

Determining the Availability of Region Monitoring
Monitoring Beacon Regions
Handling Boundary-Crossing Events
Determining the Proximity of a Beacon Using Ranging
Turning an iOS Device Into an iBeacon

Determining the Availability of Region Monitoring

Before monitoring a Beacon Region on a device, the developer should check for the availability of the region monitoring and the authorization status.To determine the availability, follow these steps:

Check the availability of the Beacon Region Monitoring.
The isMonitoringAvailableForBeaconRegions method helps determine whether a device supports Beacon Region Monitoring. If the method returns false, the application cannot use Beacon Region Monitoring. If the method returns true, the developer must check the authorization status of the Beacon Region Monitoring.
```
if (beaconManager.isMonitoringAvailableForBeaconRegions()) {
     kony.print("Monitoring is available");
     // Check for authorization status
}
```
Check the Beacon Region Monitoring Authorization Status.
The authorizationStatus method of BeaconManager object determines whether the application is currently authorized to use iOS location services for monitoring the beacons. If the authorization status is BeaconManagerAuthorizationStatusAuthorized, the application will receive boundary-crossing notifications for any region it is monitoring. If the authorization status is any other value, the application does not receive those notifications.
If the application is not authorized to use Beacon Region Monitoring, it can still register Beacon Regions for later use. If the user grants authorization to the application, monitoring for those regions will begin and will generate subsequent boundary-crossing notifications.
```
if (beaconManager.authorizationStatus() == "BeaconManagerAuthorizationStatusAuthorized") {
    kony.print("Authorized to use location services");
}
```
You can use BeaconManager’s authorizationStatusChanged callback to detect changes in authorization status to the application.
Refer to the Apple’s Location and Maps Programming Guide for more information.

Monitoring Beacon Regions

When a Beacon Region is monitored, respective callbacks are fired when the device crosses the boundary of the region. You can define a Beacon Region using the BeaconRegion class with proximityUUID, major, minor and identifier methods. The identifier is required and provides a way to refer to a particular beacon in your code. To register a Beacon Region for monitoring, call the startMonitoringBeaconRegion method of the BeaconManager object.

To monitoring Beacon Regions, follow these steps:

Create a Beacon Region object with beacon identifying information.


var aBeaconRegion = new com.kony.BeaconRegion(aProximityUUID, aMajor, aMinor, anIdentifier);

Create a Beacon Manager object with event callback functions.


function monitoringCallback(beaconRegion, state) {}

function rangingCallback(beaconRegion, beacons) {}

function errorCallback(beaconManagerError, errorName, errorDictionary, beaconRegion) {}
var aBeaconManager = new com.kony.BeaconManager(monitoringCallback, rangingCallback, errorCallback);

Start monitoring the beacon region by calling the startMonitoringBeaconRegion method of the BeaconManager object.
```
aBeaconManager.startMonitoringBeaconRegion(aBeaconRegion);
```

Handling Boundary-Crossing Events

If the device enters or exits a Beacon Region, you will be notified through the monitoringCallback of BeaconManager object. A developer can postpone these notifications until the user turns on the device’s display by calling setNotifyEntryStateOnDisplay with true.

To handle boundary-crossing events, follow these steps:

Define a monitoring callback.
A monitoring callback should accept two arguments, BeaconRegion object and Device State, of the Beacon Region. The monitoring callback is called on detection of any boundary-crossing event.
```
function monitoringCallback(beaconRegion, beaconRegionState) {
...
}
```

Handle events.

If the device enters a Beacon Region, beaconRegionState will be BeaconRegionStateInside.

If the device exits a Beacon Region, beaconRegionState will be BeaconRegionStateOutside.


function monitoringCallback(beaconRegion, beaconRegionState) {
    if (beaconRegionState == "BeaconRegionStateInside") {
        // Device is inside the beacon region -- start ranging beacons
    }
}

Determining the Proximity of a Beacon Using Ranging

A Beacon Region can be ranged to determine the proximity of the beacon from the device using the startRangingBeaconsRegion method of the BeaconManager object.

You should call the isRangingAvailableForBeaconRegions method of the BeaconManager before attempting to range beacons.

Whenever the beacons come within range or go out of range, the BeaconManager object will notify you through rangingCallback with an array of Beacon objects. The beacon objects are detected in the order of closest to farthest. Use the getProximity property to determine relative distance of the beacon to the device. Determine the beacon identifying information using other properties of the beacon object.

To determine proximity, follow these steps:

Determining the availability of beacon ranging.
The isRangingAvailableForBeaconRegions method determines whether the current device supports beacon region ranging. If the method returns false, the application cannot use beacon region ranging.
Define ranging callback for notifications.
Ranging callback should accept two arguments, a beaconRegion and array beacons, which are in range.
```
function rangingCallback(beaconRegion, beacons) {
    // Determine the proximity of beacons to the device.
}
```

Ranging beacons in a region.

To start ranging beacons in a beacon region, use startRangingBeaconsInRegion method to start ranging updates for beacons in that region.


var aBeaconRegion = new com.kony.BeaconRegion(aProximityUUID, aMajor, aMinor, anIdentifier);
var aBeaconManager = new com.kony.BeaconManager(monitoringCallback, rangingCallback, errorCallback);
aBeaconManager.startRangingBeaconsInRegion(aBeaconRegion);

Determine proximity and other properties.

In the rangingCallback, the developer can determine the relative distance of the beacon from the device.


function rangingCallback(beaconRegion, beacons) {
    for (var beacon in beacons) {
        if (beacon.getProximity() == "BeaconProximityImmediate") {
            // Immediate
        } else if (beacon.getProximity() == "BeaconProximityNear") {
            // Near
        } else { 
          // beacon.getProximity() == "BeaconProximityFar"
            // Far
        }
    }
  }

Turning an iOS Device Into an iBeacon

Any iOS device that supports sharing data using Bluetooth low energy can be used as an iBeacon. Because the application you write must run in the foreground, iBeacon support on iOS devices is intended for testing purposes and for applications that always run in the foreground, such as point-of-sale apps. For other types of iBeacon implementations, you need to acquire dedicated beacon hardware from third-party manufacturers.

To turn an iOS device into an iBeacon, follow these steps:

Create a Beacon Region object.
To use your iOS device as a beacon, you first generate a 128-bit UUID that will be your Beacon Region’s proximity UUID. Open Terminal(in Mac OS) and type uuidgen on the command line. You receive a unique 128-bit value in an ASCII string that is punctuated by hyphens, as in this example.
```
$ uuidgen
FBA1FFE5-7CD6-451B-8F1F-22B2AC70AA45
```
Next, create a Beacon Region with the UUID you generated for the beacon’s proximity UUID, defining the major and minor values as needed. Be sure to also use a unique string identifier for the new region. This code shows how to create a new Beacon Region using the example UUID above.
```
var proximityUUID = "FBA1FFE5-7CD6-451B-8F1F-22B2AC70AA45";
var major = 10;
var minor = 12;
var identifier = "KonyBeaconSample";
var beaconRegion = new com.kony.BeaconRegion(proximityUUID, major, minor, identifier);
```
Advertise the beacon information using the peripheral manager.
Now that you have created a Beacon Region, you need to advertise your beacon’s proximity UUID (and any major or minor value you specified) using the com.kony.PeripheralManager object.
```
var peripheralManager = new com.kony.PeripheralManager(stateUpdatedCallback, advertisingStatusCallback);

peripheralManager.startAdvertisingWithMeasuredPower(beaconRegion, null);
```