IBeacon

Improve this doc

$ ionic plugin add cordova-plugin-ibeacon
$ npm install --save @ionic-native/ibeacon

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

This plugin provides functions for working with iBeacons.

The plugin's API closely mimics the one exposed through the CLLocationManager introduced in iOS 7.

Supported platforms

Usage

import { IBeacon } from '@ionic-native/ibeacon';

constructor(private ibeacon: IBeacon) { }

...


// Request permission to use location on iOS
this.ibeacon.requestAlwaysAuthorization();
// create a new delegate and register it with the native layer
let delegate = this.ibeacon.Delegate();

// Subscribe to some of the delegate's event handlers
delegate.didRangeBeaconsInRegion()
  .subscribe(
    data => console.log('didRangeBeaconsInRegion: ', data),
    error => console.error();
  );
delegate.didStartMonitoringForRegion()
  .subscribe(
    data => console.log('didStartMonitoringForRegion: ', data),
    error => console.error();
  );
delegate.didEnterRegion()
  .subscribe(
    data => {
      console.log('didEnterRegion: ', data);
    }
  );

let beaconRegion = this.ibeacon.BeaconRegion('deskBeacon','F7826DA6-ASDF-ASDF-8024-BC5B71E0893E');

this.ibeacon.startMonitoringForRegion(beaconRegion)
  .then(
    () => console.log('Native layer recieved the request to monitoring'),
    error => console.error('Native layer failed to begin monitoring: ', error)
  );

Instance Members

Delegate()

Instances of this class are delegates between the LocationManager and the code that consumes the messages generated on in the native layer.

Returns: IBeaconDelegate An instance of the type {@type Delegate}.

BeaconRegion(identifier, uuid, major, minor, notifyEntryStateOnDisplay)

Creates a new BeaconRegion

Param Type Details
identifier String

@see {CLRegion}

uuid String

The proximity ID of the beacon being targeted. This value must not be blank nor invalid as a UUID.

major Number

The major value that you use to identify one or more beacons.

minor Number

The minor value that you use to identify a specific beacon.

notifyEntryStateOnDisplay BOOL

Returns: BeaconRegion Returns the BeaconRegion that was created

getDelegate()

Returns: IBeaconDelegate Returns the IBeaconDelegate

setDelegate(delegate)

Param Type Details
delegate IBeaconDelegate

An instance of a delegate to register with the native layer.

Returns: IBeaconDelegate Returns the IBeaconDelegate

onDomDelegateReady()

Signals the native layer that the client side is ready to consume messages. Readiness here means that it has a {IBeaconDelegate} set by the consumer javascript code.

The {LocationManager.setDelegate()} will implicitly call this method as well, therefore the only case when you have to call this manually is if you don’t wish to specify a {IBeaconDelegate} of yours.

The purpose of this signaling mechanism is to make the events work when the app is being woken up by the Operating System to give it a chance to handle region monitoring events for example.

If you don’t set a {IBeaconDelegate} and don’t call this method manually, an error message get emitted in the native runtime and the DOM as well after a certain period of time.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer acknowledged the request and started to send events.

isBluetoothEnabled()

Determines if bluetooth is switched on, according to the native layer.

Returns: Promise<boolean> Returns a promise which is resolved with a {Boolean} indicating whether bluetooth is active.

enableBluetooth()

Enables Bluetooth using the native Layer. (ANDROID ONLY)

Returns: Promise<void> Returns a promise which is resolved when Bluetooth could be enabled. If not, the promise will be rejected with an error.

disableBluetooth()

Disables Bluetooth using the native Layer. (ANDROID ONLY)

Returns: Promise<void> Returns a promise which is resolved when Bluetooth could be enabled. If not, the promise will be rejected with an error.

startMonitoringForRegion(region)

Start monitoring the specified region.

If a region of the same type with the same identifier is already being monitored for this application, it will be removed from monitoring. For circular regions, the region monitoring service will prioritize regions by their size, favoring smaller regions over larger regions.

This is done asynchronously and may not be immediately reflected in monitoredRegions.

Param Type Details
region Region

An instance of {Region} which will be monitored by the operating system.

Returns: Promise<string> Returns a promise which is resolved as soon as the native layer acknowledged the dispatch of the monitoring request.

stopMonitoringForRegion(region)

Stop monitoring the specified region. It is valid to call stopMonitoringForRegion: for a region that was registered for monitoring with a different location manager object, during this or previous launches of your application.

This is done asynchronously and may not be immediately reflected in monitoredRegions.

Param Type Details
region Region

An instance of {Region} which will be monitored by the operating system.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer acknowledged the dispatch of the request to stop monitoring.

requestStateForRegion(region)

Request state the for specified region. When result is ready didDetermineStateForRegion is triggered. This can be any region, also those which is not currently monitored.

This is done asynchronously and may not be immediately reflected in monitoredRegions.

Param Type Details
region Region

An instance of {Region} which will be monitored by the operating system.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer acknowledged the dispatch of the request to stop monitoring.

startRangingBeaconsInRegion(region)

Start ranging the specified beacon region.

If a region of the same type with the same identifier is already being monitored for this application, it will be removed from monitoring.

This is done asynchronously and may not be immediately reflected in rangedRegions.

Param Type Details
region Region

An instance of {BeaconRegion} which will be monitored by the operating system.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer acknowledged the dispatch of the monitoring request.

stopRangingBeaconsInRegion(region)

Stop ranging the specified region. It is valid to call stopMonitoringForRegion: for a region that was registered for ranging with a different location manager object, during this or previous launches of your application.

This is done asynchronously and may not be immediately reflected in rangedRegions.

Param Type Details
region Region

An instance of {BeaconRegion} which will be monitored by the operating system.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer acknowledged the dispatch of the request to stop monitoring.

getAuthorizationStatus()

Queries the native layer to determine the current authorization in effect.

Returns: Promise<IBeaconPluginResult> Returns a promise which is resolved with the requested authorization status.

requestWhenInUseAuthorization()

For iOS 8 and above only. The permission model has changed by Apple in iOS 8, making it necessary for apps to explicitly request permissions via methods like these: requestWhenInUseAuthorization requestAlwaysAuthorization

If you are using this plugin on Android devices only, you will never have to use this, nor {@code requestAlwaysAuthorization}

Returns: Promise<void> Returns a promise that is resolved when the request dialog is shown.

requestAlwaysAuthorization()

See the documentation of {@code requestWhenInUseAuthorization} for further details.

Returns: Promise<void> Returns a promise which is resolved when the native layer shows the request dialog.

getMonitoredRegions()

Returns: Promise<Region[]> Returns a promise which is resolved with an {Array} of {Region} instances that are being monitored by the native layer.

getRangedRegions()

Returns: Promise<Region[]> Returns a promise which is resolved with an {Array} of {Region} instances that are being ranged by the native layer.

isRangingAvailable()

Determines if ranging is available or not, according to the native layer.

Returns: Promise<boolean> Returns a promise which is resolved with a {Boolean} indicating whether ranging is available or not.

isMonitoringAvailableForClass(region)

Determines if region type is supported or not, according to the native layer.

Param Type Details
region Region

An instance of {Region} which will be checked by the operating system.

Returns: Promise<boolean> Returns a promise which is resolved with a {Boolean} indicating whether the region type is supported or not.

startAdvertising(region, measuredPower:)

Start advertising the specified region.

If a region a different identifier is already being advertised for this application, it will be replaced with the new identifier.

This call will accept a valid beacon even when no BlueTooth is available, and will start when BlueTooth is powered on. See {IBeaconDelegate.}

Param Type Details
region Region

An instance of {Region} which will be advertised by the operating system.

measuredPower: Integer

Optional parameter, if left empty, the device will use it's own default value.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer acknowledged the dispatch of the advertising request.

stopAdvertising()

Stop advertising as a beacon.

This is done asynchronously and may not be immediately reflected in isAdvertising.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer acknowledged the dispatch of the request to stop advertising.

isAdvertisingAvailable()

Determines if advertising is available or not, according to the native layer.

Returns: Promise<void> Returns a promise which is resolved with a {Boolean} indicating whether advertising is available or not.

isAdvertising()

Determines if advertising is currently active, according to the native layer.

Returns: Promise<void> Returns a promise which is resolved with a {Boolean} indicating whether advertising is active.

disableDebugLogs()

Disables debug logging in the native layer. Use this method if you want to prevent this plugin from writing to the device logs.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer has set the logging level accordingly.

enableDebugNotifications()

Enables the posting of debug notifications in the native layer. Use this method if you want to allow the plugin the posting local notifications. This can be very helpful when debugging how to apps behave when launched into the background.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer has set the flag to enabled.

disableDebugNotifications()

Disables the posting of debug notifications in the native layer. Use this method if you want to prevent the plugin from posting local notifications.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer has set the flag to disabled.

enableDebugLogs()

Enables debug logging in the native layer. Use this method if you want a debug the inner workings of this plugin.

Returns: Promise<void> Returns a promise which is resolved as soon as the native layer has set the logging level accordingly.

appendToDeviceLog(message)

Appends the provided [message] to the device logs. Note: If debug logging is turned off, this won’t do anything.

Param Type Details
message String

The message to append to the device logs.

Returns: Promise<void> Returns a promise which is resolved with the log message received by the native layer for appending. The returned message is expected to be equivalent to the one provided in the original call.

Beacon

Param Type Details
uuid string

The physical device's identifier.

major number

The beacon's major identifier number.

minor number

The beacon's major identifier number.

proximity 'ProximityImmediate' | 'ProximityNear' | 'ProximityFar' | 'ProximityUnknown'

The proximity of the beacon relative to the phone.

Possible options are: ProximityImmediate ProximityNear ProximityFar ProximityUnknown

tx number

Transmission Power of the beacon. A constant emitted by the beacon which indicates what's the expected RSSI at a distance of 1 meter to the beacon.

rssi number

Received Signal Strength Indicator. The strength of the beacon's signal when it reaches the device. RSSI ranges from aprox -26 (a few inches) to -100 (40-50 m distance).

accuracy number

The accuracy of the ranging.

BeaconRegion

Param Type Details
identifier string

A unique identifier for this region.

uuid string

The the beacon identifier the device will "watch" for. Many beacons can share the same uuid.

major number

The beacon's major identifier number. Optional, of nothing is supplied the plugin will treat it as a wildcard.

(optional)
minor number

The beacon's minor identifier number. Optional, of nothing is supplied the plugin will treat it as a wildcard.

(optional)
notifyEntryStateOnDisplay boolean

If set to true the device will scan for beacons and determine region state anytime the device's screen is turned on or off. Useful for debugging.

(optional)

CircularRegion

Param Type Details
identifier string

A unique identifier for this region.

latitude number

The latitude of this region.

longitude number

The longitude of this region.

radius number

The radius of the geofence for this region.

IBeaconPluginResult

Param Type Details
eventType string

The name of the delegate function that produced the PluginResult object.

region Region

The region that triggered the event.

beacons Beacon[]

An array of beacon objects

authorizationStatus string

The status of the location permission for iOS.

state 'CLRegionStateInside' | 'CLRegionStateOutside'

The state of the phone in relation to the region. Inside/outside for example.

error string

Error message, used only with monitoringDidFailForRegionWithError delegate.

IBeaconDelegate

Param Type Details
didChangeAuthorizationStatus Observable<string>

An observable that publishes information about the location permission authorization status.

didDetermineStateForRegion Observable<IBeaconPluginResult>

An Observable that publishes event data to it's subscribers when the native layer is able to determine the device's state.

This event is called when the phone begins starts monitoring, when requestStateForRegion is called, etc.

didEnterRegion Observable<IBeaconPluginResult>

An Observable that publishes event data to it's subscribers when the phone enters a region that it was asked to monitor.

If the user has given the app Always-Location permission, this function will be called even when the app is not running on iOS. The app will run silently in the background for a small amount of time.

didExitRegion Observable<IBeaconPluginResult>

An Observable that publishes event data to it's subscribers when the phone exits a region that it was asked to monitor.

If the user has given the app Always-Location permission, this function will be called even when the app is not running on iOS. The app will run silently in the background for a small amount of time.

didRangeBeaconsInRegion Observable<IBeaconPluginResult>

An Observable that publishes event data to it's subscribers each time that the device ranges beacons. Modern Android and iOS devices range aproximately once per second.

didStartMonitoringForRegion Observable<IBeaconPluginResult>

An Observable that publishes event data to it's subscribers when the device begins monitoring a region.

monitoringDidFailForRegionWithError Observable<IBeaconPluginResult>

An Observable that publishes event data to it's subscribers when the device fails to monitor a region.

peripheralManagerDidStartAdvertising Observable<IBeaconPluginResult>

An Observable that publishes event data to it's subscribers when the device begins advertising as an iBeacon.

peripheralManagerDidUpdateState Observable<IBeaconPluginResult>

An Observable that publishes event data to it's subscribers when the state of the peripheral manager's state updates.

API

Native

General