# Modules.BLE.RegionManager

An object that manages and scan beacons.

Availability

1.1.0

Extends

Titanium.Proxy

# Properties

# apiName READONLY

Availability

3.2.0

apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# bubbleParent

Availability

3.0.0

bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# isMonitoringAvailable READONLY

Availability

1.1.0

isMonitoringAvailable :Boolean

Determines whether the device supports monitoring for the specified type of region.

If false, all attempts to monitor the specified type of region will fail.

# isRangingAvailable READONLY

Availability

1.1.0

isRangingAvailable :Boolean

Determines whether the device supports ranging.

If false, all attempts to range beacons will fail.

# locationManagerAuthorizationStatus READONLY

Availability

1.1.0

locationManagerAuthorizationStatus :Number

Returns the current authorization status of the calling application.

# locationServicesEnabled READONLY

Availability

1.1.0

locationServicesEnabled :Boolean

Determines whether the user has location services enabled.

If false, and you proceed to call other CoreLocation API, user will be prompted with the warning dialog. You may want to check this property and use location services only when explicitly requested by the user.

# maximumRegionMonitoringDistance READONLY

Availability

1.1.0

maximumRegionMonitoringDistance :Number

The maximum region size, in terms of a distance from a central point, that the framework can support.

Attempts to register a region larger than this will generate a kCLErrorRegionMonitoringFailure. This value may vary based on the hardware features of the device, as well as on dynamically changing resource constraints.

# monitoredRegions READONLY

Availability

1.1.0

monitoredRegions :Array<Modules.BLE.BeaconRegion>

Retrieve a set of objects for the regions that are currently being monitored.

If manager has been instructed to monitor a region, during this or previous launches of your application, it will be present in this set.

# rangedBeaconConstraints READONLY

Availability

1.1.0

rangedBeaconConstraints :Array<Modules.BLE.BeaconIdentityConstraint>

Retrieve a set of beacon constraints for which this location manager is actively providing ranging.

# rangedRegions READONLY

Availability

1.1.0

rangedRegions :Array<Modules.BLE.BeaconRegion>

Retrieve a set of objects representing the regions for which this location manager is actively providing ranging.

# Methods

# addEventListener

Availability

1.1.0

addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to invoke when the event is fired.

Returns

Type: void

# applyProperties

Availability

3.0.0

applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name	Type	Description
`props`	Dictionary	A dictionary of properties to apply.

Returns

Type: void

# fireEvent

Availability

1.1.0

fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`event`	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type: void

# removeEventListener

Availability

1.1.0

removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`.

Returns

Type: void

# requestAlwaysAuthorization

Availability

1.1.0

requestAlwaysAuthorization() → void

When locationManagerAuthorizationStatus == LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, calling this method will start the process of requesting "LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_ALWAYS" authorization from the user.

An application which currently has "LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_WHEN_IN_USE" authorization and has never before requested "LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_ALWAYS" authorization may use this method to request "LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_ALWAYS" authorization one time only. Note: To call this method, you must have both NSLocationAlwaysUsageDescription and NSLocationWhenInUseUsageDescription keys in your app’s tiapp.xml file.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Allow Location permission</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Allow Location permission</string>

For More Info: https://developer.apple.com/documentation/corelocation/cllocationmanager/1620551-requestalwaysauthorization

Returns

Type: void

# requestRegionState

Availability

1.1.0

requestRegionState(beaconRegion) → void

Asynchronously retrieve the cached state of the specified region. The state is returned to the "didDetermineState" event

Parameters

Name	Type	Description
`beaconRegion`	Modules.BLE.BeaconRegion	Beacon region which state is requested

Returns

Type: void

# requestWhenInUseAuthorization

Availability

1.1.0

requestWhenInUseAuthorization() → void

When locationManagerAuthorizationStatus == LOCATION_MANAGER_AUTHORIZATION_STATUS_NOT_DETERMINED, calling this method will trigger a prompt to request "LOCATION_MANAGER_AUTHORIZATION_STATUS_AUTHORIZED_WHEN_IN_USE" authorization from the user.

Note: 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 tiapp.xml file, and the presence of that key is required when calling this method. The user prompt displays the following options, which determine the authorization your app can receive.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Allow Location permission</string>

Returns

Type: void

# startRangingBeaconsInRegion

Availability

1.1.0

startRangingBeaconsInRegion(beaconRegion) → void

Start calculating ranges for beacons in the specified region.

Parameters

Name	Type	Description
`beaconRegion`	Modules.BLE.BeaconRegion	Beacon region object

Returns

Type: void

# startRangingBeaconsSatisfyingIdentityConstraint

Availability

1.1.0

startRangingBeaconsSatisfyingIdentityConstraint(identityConstraint) → void

Start calculating ranges for beacons in the specified region.

Parameters

Name	Type	Description
`identityConstraint`	Modules.BLE.BeaconIdentityConstraint	Beacon identity constraint object

Returns

Type: void

# startRegionMonitoring

Availability

1.1.0

startRegionMonitoring(beaconRegion) → void

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. Note: This is done asynchronously and may not be immediately reflected in monitoredRegions.

Parameters

Name	Type	Description
`beaconRegion`	Modules.BLE.BeaconRegion	Beacon region object

Returns

Type: void

# stopRangingBeaconsInRegion

Availability

1.1.0

stopRangingBeaconsInRegion(beaconRegion) → void

Stop calculating ranges for the specified region.

Parameters

Name	Type	Description
`beaconRegion`	Modules.BLE.BeaconRegion	Beacon region object

Returns

Type: void

# stopRangingBeaconsSatisfyingIdentityConstraint

Availability

1.1.0

stopRangingBeaconsSatisfyingIdentityConstraint(identityConstraint) → void

Stop an earlier beacon ranging request. See startRangingBeaconsSatisfyingIdentityConstraint:.

Parameters

Name	Type	Description
`identityConstraint`	Modules.BLE.BeaconIdentityConstraint	Beacon identity constraint object

Returns

Type: void

# stopRegionMonitoring

Availability

1.1.0

stopRegionMonitoring(beaconRegion) → void

Stop monitoring the specified region.

It is valid to call stopMonitoring for a region that was registered for monitoring with a different region manager object, during this or previous launches of your application. Note: This is done asynchronously and may not be immediately reflected in monitoredRegions.

Parameters

Name	Type	Description
`beaconRegion`	Modules.BLE.BeaconRegion	Beacon region object

Returns

Type: void

# Events

# didEnterRegion

Availability

1.1.0

Invoked when the user enters a monitored region.

Properties

Name	Type	Description
region	Modules.BLE.BeaconRegion	Beacon region object
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didExitRegion

Availability

1.1.0

Invoked when the user exits a monitored region

Properties

Name	Type	Description
region	Modules.BLE.BeaconRegion	Beacon region object
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didRangeBeacons

Availability

1.1.0

Invoked when a new set of beacons are available in the specified region

If beacons is empty, it may be assumed no beacons that match the specified region are nearby. Similarly if a specific beacon no longer appears in beacons, it may be assumed the beacon is no longer received by the device.

Properties

Name	Type	Description
region	Modules.BLE.BeaconRegion	Beacon region object
beacons	Array<Modules.BLE.Beacon>	Beacon objects
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didRange

Availability

1.1.0

Invoked when a new set of beacons are available in the specified Beacon Identity Constraint

If beacons is empty, it may be assumed no beacons that match the specified Beacon Identity Constraint are nearby. Similarly if a specific beacon no longer appears in beacons, it may be assumed the beacon is no longer received by the device.

Properties

Name	Type	Description
beaconConstraint	Modules.BLE.BeaconIdentityConstraint	Beacon Identity Constraint object
beacons	Array<Modules.BLE.Beacon>	Beacon objects
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didFailRanging

Availability

1.1.0

Invoked when an error has occurred ranging beacons in a region.

Properties

Name	Type	Description
beaconConstraint	Modules.BLE.BeaconIdentityConstraint	Beacon Identity Constraint object
errorCode	String	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 any
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didFail

Availability

1.1.0

Invoked when an any error has occurred.

Properties

Name	Type	Description
errorCode	String	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 any
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# rangingBeaconsDidFail

Availability

1.1.0

Invoked when an error has occurred ranging beacons in a region.

Properties

Name	Type	Description
region	Modules.BLE.BeaconRegion	Beacon region object
errorCode	String	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 any
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didDetermineState

Availability

1.1.0

Invoked when there's a state transition for a monitored region or in response to a request for state via a call to "requestRegionState"

Properties

Name	Type	Description
region	Modules.BLE.BeaconRegion	Beacon region object
state	Number	current state value. see REGION_STATE_* for possible values
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didStartMonitoring

Availability

1.1.0

Invoked when a monitoring for a region started successfully.

Properties

Name	Type	Description
region	Modules.BLE.BeaconRegion	Beacon region object
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# monitoringDidFail

Availability

1.1.0

Invoked when an error has occurred monitoring beacons in a region.

Properties

Name	Type	Description
region	Modules.BLE.BeaconRegion	Beacon region object
errorCode	String	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 any
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# didChangeAuthorization

Availability

1.1.0

Invoked when the authorization status changes for this application.

Properties

Name	Type	Description
state	Number	current authorization value. see LOCATION_MANAGER_AUTHORIZATION_STATUS_* for possible values
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.