Logical Labs Beacons Module for Android

API Docs for: 1.2.5
Show:

BeaconsModule Class

Module: Readme

Methods

clearAppLaunchIntent

() Void

Available since 1.2.0

Use this function to instruct the module not to launch the app when the user enters a monitored region.

Returns:

Void:

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:

disable

() Boolean

Available since 1.0.0

Disables the Bluetooth adapter.

Returns:

Boolean:

Returns true if the Bluetooth adapter was successfully disabled.

enable

() Boolean

Available since 1.0.0

Enables the Bluetooth adapter.

Returns:

Boolean:

Returns true if the Bluetooth adapter was successfully enabled.

getState

() Number

Available since 1.0.0

Returns the current state of the local Bluetooth adapter.

See also the STATE_OFF, STATE_ON, STATE_TURNING_OFF, and STATE_TURNING_ON constants.

Returns:

Number:

isAppLaunchConfigured

() Boolean

Available since 1.2.0

Determines whether the module is currently configured to launch the app when BLE activity is detected.

Returns:

Boolean:

isEnabled

() Boolean

Available since 1.0.0

Determines whether the Bluetooth adapter is enabled and ready for use.

Returns:

Boolean:

Returns true if Bluetooth is currently enabled.

isSupported

() Boolean

Available since 1.0.0

Determines whether the device is capable of communicating with other devices via Bluetooth Low Energy radio.

Returns:

Boolean:

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:

retrieveMonitoredRegions

() Void

Available since 1.2.5

Retrieves the currently monitored beacon regions.

Async function; returns the results in a retrievedMonitoredRegions event.

Returns:

Void:

setAppLaunchIntent

(
  • params
)
Void

Available since 1.2.0

Specifies the parameters for the intent the module is expected to use to launch the app. Use this function to instruct the module to launch the app when the user enters a monitored region.

The intent launching the app will have an extra called eventName, which is a string holding the name of the event that caused the module to launch the app.

Parameters:

  • params Object
    • packageName String

      The package name of the app to be launched by the module.

    • className String

      The name of the class (typically the app's main activity) to be launched by the module.

Returns:

Void:

setScanTimers

(
  • params
)
Void

Available since 1.2.0

Use this function to control the timing of beacon related scanning. By default, scanning is restarted every 1.1 seconds while region monitoring or beacon ranging is enabled, to be able to provide beacon related events in a timely manner. You can use this function to increase the scan interval if less frequent beacon related events are sufficient for your use case.

Note that these timers don't impact general scanning unless general scanning is used in parallel with beacon related functionality. See the Beacon Support section of the Readme for more information.

Calling this function will reset scanning to make sure the new timers take effect immediately.

Parameters:

  • params Object
    • scanPeriod Number

      Scan period in milliseconds. This is how long each scanning session lasts.

    • scanPausePeriod Number

      Scan pause period in milliseconds. This is the time gap between scan periods.

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. If that old region was being ranged, then so will 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:

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. Note that the region is being identified by its identifier property, not the UUID!

Parameters:

  • [params] Object optional

    An object with the following properties:

Returns:

Void:

Properties

filterDuplicateBeacons

Boolean

Available since 1.1.0

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.

monitoredRegions

Array of BeaconRegions read-only

Available since 1.1.0

The beacon regions currently being monitored by the module.

rangedRegions

Array of BeaconRegions read-only

Available since 1.2.0

The beacon regions currently being ranged by the module.

state

Number read-only

Available since 1.0.0

The current state of the local Bluetooth adapter.

See also the STATE_OFF, STATE_ON, STATE_TURNING_OFF, and STATE_TURNING_ON constants.

Constants

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.

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_UNKNOWN

Number

Available since 1.1.0

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

STATE_OFF

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is turned off.

STATE_ON

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is turned on.

STATE_TURNING_OFF

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is about to turn off.

STATE_TURNING_ON

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is about to turn on.

Events

enteredRegion

Available since 1.1.0

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

Event Payload:

exitedRegion

Available since 1.1.0

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

Event Payload:

moduleReady

Available since 1.2.0

This event is fired when the module is ready. Wait for this event before calling any methods on the module.

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.