Logical Labs Beacons Module for iOS

API Docs for: 1.2.7
Show:

BeaconsModule Class

Module: Readme

Item Index

Methods

Properties

Constants

Events

Methods

createBeaconRegion

(
  • params
)
Void

Available since 1.1.0

Creates a BeaconRegion object that can be used to start advertising an iBeacon.

Parameters:

  • params Object

    An object with the following properties (see the properties of the BeaconRegion class for details):

    • identifier String

      A unique identifier to associate with the returned region object. You use this identifier to differentiate regions within your application.

    • UUID String

      The UUID of the beacon.

    • [major] Number optional

      The major number of the beacon. If not specified, the major and minor numbers of the beacon are ignored.

    • [minor] Number optional

      The minor number of the beacon. If not specified, the minor number of the beacon is ignored.

    • [notifyEntryStateOnDisplay=false] Boolean optional

      When set to true, the beacon notifications will be sent only when the user turns on the display and the device is already inside the region.

Returns:

Void:

initPeripheralManager

(
  • [params]
)
Void

Available since 1.0.0

Initializes the module's internal peripheral manager object. This function must be called in an app that acts as a peripheral before any other function can be used.

Parameters:

  • [params] Object optional

    An object with the following properties:

    • [showPowerAlert=true] Boolean optional

      Boolean indicating that the system should, if Bluetooth is powered off when the peripheral is instantialized, display a warning dialog to the user. This parameter was introduced in version 1.1.0 of the module.

    • [restoreIdentifier] String optional

      A string containing a unique identifier for the peripheral manager that is being instantiated. This identifier is used by the system to identify a specific peripheral manager instance for restoration and, therefore, must remain the same for subsequent application executions in order for the manager to be restored. See also the peripheralWillRestoreState event. This parameter was introduced in version 1.1.0 of the module.

Returns:

Void:

requestAlwaysAuthorization

() Void

Available since 1.2.7

When the current authorization status is LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, this method runs asynchronously and prompts the user to grant permission to the app to use location services. The user prompt contains the text from the NSLocationAlwaysUsageDescription key in your app’s Info.plist file. The presence of that key is required when calling this method.

After the status is determined, the app will receive an BeaconsModule/locationManagerAuthorizationChanged:event event.

If the current authorization status is anything other than LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, this function does nothing.

Important: You must call this function or the requestWhenInUseAuthorization function prior to using beacon services.

Requesting “Always” authorization is discouraged by Apple 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.

Returns:

Void:

requestRegionState

(
  • params
)
Void

Available since 1.2.4

Retrieves the state of a region asynchronously.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

requestWhenInUseAuthorization

() Void

Available since 1.2.7

When the current authorization status is LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, this method runs asynchronously and prompts the user to grant permission to the app to use location services. The user prompt contains the text from the NSLocationWhenInUseUsageDescription key in your app’s Info.plist file. The presence of that key is required when calling this method.

After the status is determined, the app will receive an BeaconsModule/locationManagerAuthorizationChanged:event event.

If the current authorization status is anything other than LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, this function does nothing.

Important: You must call this function or the requestAlwaysAuthorization function prior to using beacon services.

If the user grants “when-in-use” authorization to your app, your app can range beacons but not monitor beacon regions.

Returns:

Void:

retrieveMonitoredRegions

() Void

Available since 1.2.5

Retrieves the currently monitored beacon regions. Note that this function will initialize the location manager if it's not already initialized. Thus this function, unlike the monitoredRegions property, is guaranteed to return the correct result in every case. In particular, this function is a key component of the restoration process that needs to take place when the app is restarted into the background in response to a beacon related event.

Important: Call this function after you attached the appropriate event handlers for the enteredRegion, exitedRegion, and regionStateUpdated events. If the app was restarted due to a beacon related event, that event will be fired immediately after this function is called.

Async function; returns the results in a retrievedMonitoredRegions event.

Returns:

Void:

startAdvertising

(
  • [params]
)
Void

Available since 1.0.0

Instructs the module's internal peripheral manager to start advertising.

Important: You must call the initPeripheralManager function first!

Note: In the Beacons module, this function can only be used to advertise beacon regions.

Supported advertising data types are ADVERT_DATA_KEY_LOCAL_NAME and ADVERT_DATA_KEY_SERVICE_UUIDS. When in the foreground, an application can utilize up to 28 bytes of space in the initial advertisement data for any combination of the supported advertising data types. If this space is used up, there are an additional 10 bytes of space in the scan response that can be used only for the local name. Note that these sizes do not include the 2 bytes of header information that are required for each new data type. Any service UUIDs that do not fit in the allotted space will be added to a special "overflow" area, and can only be discovered by an iOS device that is explicitly scanning for them. While an application is in the background, the local name will not be used and all service UUIDs will be placed in the "overflow" area.

Parameters:

  • [params] Object optional

    Object containing the data to be advertised.

    • ADVERT_DATA_KEY_LOCAL_NAME String

      Local name. Note that ADVERT_DATA_KEY_LOCAL_NAME is the constant whose value (!) is to be used as the key, like so: params[BluetoothLE.ADVERT_DATA_KEY_LOCAL_NAME] = ...

    • ADVERT_DATA_KEY_SERVICE_UUIDS Array of Strings

      Service UUIDs. Note that ADVERT_DATA_KEY_SERVICE_UUIDS is the constant whose value (!) is to be used as the key, like so: params[BluetoothLE.ADVERT_DATA_KEY_SERVICE_UUIDS] = ...

    • beaconRegion BeaconRegion

      An object created using the createBeaconRegion method. If this parameter is present, other parameters except measuredPower are ignored.

    • [measuredPower] Number optional

      The received signal strength indicator (RSSI) value (measured in decibels) for the device. This value represents the measured strength of the beacon from one meter away and is used during ranging. If not specified, the default value for the device will be used.

Returns:

Void:

startRangingBeacons

(
  • params
)
Void

Available since 1.1.0

Starts the delivery of notifications for beacons in the specified region.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

startRegionMonitoring

(
  • params
)
Void

Available since 1.1.0

Starts monitoring the specified region.

You must call this method once for each region you want to monitor. If an existing region with the same identifier is already being monitored by the application, the old region is replaced by the new one. Note that "identifier" literally means the identifier property, not the UUID! The regions you add using this method are stored in the monitoredRegions property.

Parameters:

  • params Object

    An object with the following properties:

Returns:

Void:

stopAdvertising

() Void

Available since 1.0.0

Instructs the module's internal peripheral manager to stop advertising.

Returns:

Void:

stopRangingBeacons

(
  • [params]
)
Void

Available since 1.1.0

Stops the delivery of notifications for beacons in the specified region. If no beacon region is specified, then it stops ranging for all regions.

Parameters:

  • [params] Object optional

    An object with the following properties:

Returns:

Void:

stopRegionMonitoring

(
  • [params]
)
Void

Available since 1.1.0

Stops the delivery of notifications for beacons in the specified region. If no beacon region is specified, then it stops ranging for all regions.

Parameters:

  • [params] Object optional

    An object with the following properties:

Returns:

Void:

Properties

backgroundDataAuthorizationStatus

Number read-only

Available since 1.1.0

The current authorization status for sharing data while backgrounded. You can use it to detect restricted access and hide UI instead of prompting for access. Possible values are the BACKGROUND_DATA_AUTHORIZATION_STATUS_* constants.

filterDuplicateBeacons

Boolean

Available since 1.1.2

Determines whether the beacons included with the rangedBeacons event will be filtered for duplicates. Defaults to false. A beacon is considered a duplicate of another if their UUID, major, and minor numbers are all the same.

isAdvertising

Boolean read-only

Available since 1.0.0

Whether or not the the module's internal peripheral manager is currently advertising data.

locationManagerAuthorizationStatus

Number read-only

Available since 1.1.2

Authorization status of the Location Manager for this app. Its value is one of the LOCATION_MANAGER_AUTHORIZATION_STATUS_* constants.

monitoredRegions

Array of BeaconRegions read-only

Available since 1.1.0

The beacon regions monitored by all location manager objects. Note that this property will be undefined when the app is restarted into the background. Use the retrieveMonitoredRegions function to retrieve the list of monitored regions in that case.

peripheralManagerState

Number read-only

Available since 1.0.0

State of the module's internal peripheral manager. Its value is one of the PERIPHERAL_MANAGER_STATE_* constants.

rangedRegions

Array of BeaconRegions read-only

Available since 1.1.2

The regions currently being tracked using ranging.

restoredPeripheralManagerIdentifiers

Array of Strings read-only

Available since 1.2.5

Each string in the array represents the restoration identifier for a peripheral manager object. This is the same string you assigned to the restoreIdentifier parameter of the {{#crossLink "BeaconsModule/initPeripheralManager:method}}{{/crossLink}} function.

wasLocationLaunch

Boolean read-only

Available since 1.2.5

True if the application was launched due to a location event. In the context of this module, a "location event" is an event related to beacons. Note however that other type of location events might also trigger the app to be launched.

Constants

BACKGROUND_DATA_AUTHORIZATION_STATUS_AUTHORIZED

Number

Available since 1.1.0

One of the possible values of the backgroundDataAuthorizationStatus property. User has authorized this application to share data while backgrounded.

BACKGROUND_DATA_AUTHORIZATION_STATUS_DENIED

Number

Available since 1.1.0

One of the possible values of the backgroundDataAuthorizationStatus property. User has explicitly denied this application from sharing data while backgrounded.

BACKGROUND_DATA_AUTHORIZATION_STATUS_NOT_DETERMINED

Number

Available since 1.1.0

One of the possible values of the backgroundDataAuthorizationStatus property. User has not yet made a choice with regards to this application.

BACKGROUND_DATA_AUTHORIZATION_STATUS_RESTRICTED

Number

Available since 1.1.0

One of the possible values of the backgroundDataAuthorizationStatus property. This application is not authorized to share data while backgrounded. The user cannot change this application’s status, possibly due to active restrictions such as parental controls being in place.

BEACON_PROXIMITY_FAR

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_IMMEDIATE

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_NEAR

Number

Available since 1.1.0

One of the possible values of the proximity property.

BEACON_PROXIMITY_UNKNOWN

Number

Available since 1.1.0

One of the possible values of the proximity property.

LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED

Number

Available since 1.1.2

One of the possible values of the locationManagerAuthorizationStatus property. User has authorized this application to share data while backgrounded.

LOCATION_MANAGER_AUTHORIZATION_STATUS_DENIED

Number

Available since 1.1.2

One of the possible values of the locationManagerAuthorizationStatus property. The user explicitly denied the use of location services for this application or location services are currently disabled in Settings.

LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED

Number

Available since 1.1.2

One of the possible values of the locationManagerAuthorizationStatus property. The user has not yet made a choice regarding whether this application can use location services.

LOCATION_MANAGER_AUTHORIZATION_STATUS_RESTRICTED

Number

Available since 1.1.2

One of the possible values of the locationManagerAuthorizationStatus property. The user cannot change this application’s status, possibly due to active restrictions such as parental controls being in place.

PERIPHERAL_MANAGER_STATE_POWERED_OFF

Number

Available since 1.0.0

Bluetooth is currently powered off.

PERIPHERAL_MANAGER_STATE_POWERED_ON

Number

Available since 1.0.0

Bluetooth is currently powered on and available to use.

PERIPHERAL_MANAGER_STATE_RESETTING

Number

Available since 1.0.0

The connection with the system service was momentarily lost, update imminent.

PERIPHERAL_MANAGER_STATE_UNAUTHORIZED

Number

Available since 1.0.0

The application is not authorized to use the Bluetooth Low Energy Peripheral role.

PERIPHERAL_MANAGER_STATE_UNINITIALIZED

Number

Available since 1.0.0

This state is reported when the peripheral manager object maintained by the module does not (yet) exist, i.e. before initPeripheralManager is called or after BeaconsModule/releasePeripheralManager:method is called.

PERIPHERAL_MANAGER_STATE_UNKNOWN

Number

Available since 1.0.0

State unknown, update imminent.

PERIPHERAL_MANAGER_STATE_UNSUPPORTED

Number

Available since 1.0.0

The platform doesn't support the Bluetooth Low Energy Peripheral role.

REGION_STATE_INSIDE

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

REGION_STATE_OUTSIDE

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

REGION_STATE_UNKOWN

Number

Available since 1.1.0

One of the possible values of the state property of the regionStateUpdated event.

Events

enteredRegion

Available since 1.1.0

This event is fired when the user enters a monitored region.

Note: In our testing we found this event to be unreliable. This seems to be a problem with the native SDK. We recommend to use the regionStateUpdated event instead.

Event Payload:

exitedRegion

Available since 1.1.0

This event is fired when the user exits a monitored region.

Note: In our testing we found this event to be unreliable. This seems to be a problem with the native SDK. We recommend to use the regionStateUpdated event instead.

Event Payload:

moduleReady

Available since 1.2.0

This event is fired when the module is ready. On iOS, this is a formality; On Android, you need to wait for this event before calling any methods on the module.

peripheralManagerStateChange

Available since 1.0.0

Fired whenever the state of the module's internal peripheral manager changes.

Event Payload:

  • state Number

    An integer describing the state of the module's internal peripheral manager. See the PERIPHERAL_MANAGER_STATE_* constants.

peripheralWillRestoreState

Available since 1.1.0

Note: This event is currently not being fired, due to a limitation in Titanium. See the "iOS to iOS" sample app for a potential workaround.

Fired when iOS relaunches the app into the background (after iOS terminated it to free up resources) to complete some Bluetooth-related task. Use this event to synchronize your app's state with the state of the Bluetooth system.

See also the restoreIdentifier parameter of the initPeripheralManager method.

Event Payload:

  • services Array of Services

    An array of Service objects containing all services that were published to the local database at the time the application was terminated by the system. All the information about a service is restored, including any included services, characteristics, characteristic descriptors, and subscribed centrals.

  • advertisementData Object

    An object (dictionary) containing the data being advertised at the time the application was terminated by the system. See the startAdvertising method for more detail.

proximityChange

Available since 1.1.2

Use this event to determine which beacons have changed their proximity since the last update. This event is fired whenever the rangedBeacons event is fired, provided that the proximity of any of the ranged beacons has changed since the last rangedBeacons event.

Event Payload:

  • beacons Array of Beacons

    An array of Beacon objects representing the beacons that changed their proximity since the last update.

rangedBeacons

Available since 1.1.0

Use this event to determine which beacons are in range.

See also the filterDuplicateBeacons property.

Event Payload:

  • beacons Array of Beacons

    An array of Beacon objects representing the beacons currently in range. You can use the information in these objects to determine the range of each beacon and its identifying information.

  • region BeaconRegion

    The region object containing the parameters that were used to locate the beacons.

regionStateUpdated

Available since 1.1.0

This event is fired when the state of a monitored region is updated.

Event Payload:

  • region BeaconRegion

    The region object containing the parameters that were used to locate the beacons.

  • state Number

    One of the REGION_STATE_* constants.

retrievedMonitoredRegions

Available since 1.2.5

Returns the result of the retrieveMonitoredRegions function.

Event Payload:

  • beaconRegions Array of BeaconRegions

    An array of BeaconRegion objects, representing the currently monitored beacon regions.

startedAdvertising

This event returns the result of a startAdvertising call. If advertisement could not be started, the cause will be detailed in the errorCode, errorDomain, and errorDescription properties.

Event Payload:

  • errorCode Number

    The error code; only present if an error occurred.

  • errorDomain String

    The error domain; only present if an error occurred.

  • errorDescription String

    The error description; only peresent if an