Modules.BLE.RegionManager
An object that manages and scan beacons.
Extends: Titanium.Proxy · Since: 1.1.0 · Platforms: iphone, ipad
Properties #
isMonitoringAvailable#
Type: 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#
Type: Boolean
Determines whether the device supports ranging.
If false, all attempts to range beacons will fail.
locationManagerAuthorizationStatus#
Type: Number
Returns the current authorization status of the calling application.
locationServicesEnabled#
Type: 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#
Type: 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#
Type: 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#
Type: Array<Modules.BLE.BeaconIdentityConstraint>
Retrieve a set of beacon constraints for which this location manager is actively providing ranging.
rangedRegions#
Type: Array<Modules.BLE.BeaconRegion>
Retrieve a set of objects representing the regions for which this location manager is actively providing ranging.
Methods #
requestAlwaysAuthorization #
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: void
requestRegionState #
Asynchronously retrieve the cached state of the specified region. The state is returned to the "didDetermineState" event
| Name | Type | Summary | Optional |
|---|---|---|---|
beaconRegion | Modules.BLE.BeaconRegion | Beacon region which state is requested | No |
Returns: void
requestWhenInUseAuthorization #
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: void
startRangingBeaconsInRegion #
Start calculating ranges for beacons in the specified region.
| Name | Type | Summary | Optional |
|---|---|---|---|
beaconRegion | Modules.BLE.BeaconRegion | Beacon region object | No |
Returns: void
startRangingBeaconsSatisfyingIdentityConstraint #
Start calculating ranges for beacons in the specified region.
| Name | Type | Summary | Optional |
|---|---|---|---|
identityConstraint | Modules.BLE.BeaconIdentityConstraint | Beacon identity constraint object | No |
Returns: void
startRegionMonitoring #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
beaconRegion | Modules.BLE.BeaconRegion | Beacon region object | No |
Returns: void
stopRangingBeaconsInRegion #
Stop calculating ranges for the specified region.
| Name | Type | Summary | Optional |
|---|---|---|---|
beaconRegion | Modules.BLE.BeaconRegion | Beacon region object | No |
Returns: void
stopRangingBeaconsSatisfyingIdentityConstraint #
Stop an earlier beacon ranging request. See startRangingBeaconsSatisfyingIdentityConstraint:.
| Name | Type | Summary | Optional |
|---|---|---|---|
identityConstraint | Modules.BLE.BeaconIdentityConstraint | Beacon identity constraint object | No |
Returns: void
stopRegionMonitoring #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
beaconRegion | Modules.BLE.BeaconRegion | Beacon region object | No |
Returns: void
Events #
didChangeAuthorization #
Invoked when the authorization status changes for this application.
| Name | Type | Summary |
|---|---|---|
state | Number | current authorization value. see LOCATION_MANAGER_AUTHORIZATION_STATUS_* for possible values |
didDetermineState #
Invoked when there's a state transition for a monitored region or in response to a request for state via a call to "requestRegionState"
| Name | Type | Summary |
|---|---|---|
region | Modules.BLE.BeaconRegion | Beacon region object |
state | Number | current state value. see REGION_STATE_* for possible values |
didEnterRegion #
Invoked when the user enters a monitored region.
| Name | Type | Summary |
|---|---|---|
region | Modules.BLE.BeaconRegion | Beacon region object |
didExitRegion #
Invoked when the user exits a monitored region
| Name | Type | Summary |
|---|---|---|
region | Modules.BLE.BeaconRegion | Beacon region object |
didFail #
Invoked when an any error has occurred.
| Name | Type | Summary |
|---|---|---|
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 |
didFailRanging #
Invoked when an error has occurred ranging beacons in a region.
| Name | Type | Summary |
|---|---|---|
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 |
didRange #
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.
| Name | Type | Summary |
|---|---|---|
beaconConstraint | Modules.BLE.BeaconIdentityConstraint | Beacon Identity Constraint object |
beacons | Array<Modules.BLE.Beacon> | Beacon objects |
didRangeBeacons #
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.
| Name | Type | Summary |
|---|---|---|
region | Modules.BLE.BeaconRegion | Beacon region object |
beacons | Array<Modules.BLE.Beacon> | Beacon objects |
didStartMonitoring #
Invoked when a monitoring for a region started successfully.
| Name | Type | Summary |
|---|---|---|
region | Modules.BLE.BeaconRegion | Beacon region object |
monitoringDidFail #
Invoked when an error has occurred monitoring beacons in a region.
| Name | Type | Summary |
|---|---|---|
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 |
rangingBeaconsDidFail #
Invoked when an error has occurred ranging beacons in a region.
| Name | Type | Summary |
|---|---|---|
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 |