2018-02-21
1.0.0
OutSystems Experts
All
All
Plug-ins
[Overview]
Empower your OutSystems mobile application with iBeacons support. Monitor for Regions and scan Beacons easily!
[Detail]
iBeacons Plugins Documentation
iBeacons Plugin enables your OutSystems mobile application to leverage beacons functionalities such as beacon scanning and region monitoring on both Android and iOS platforms.
API/Client Actions
Action/Description
CheckIBeaconPlugin
Checks if both cordova and iBeacons Plugin is available for usage.
GetAuthorizationStatus
Queries the devices for authorization status. On Android, checks if Bluetooth usage is allowed and if Bluetooth is enabled. On iOS, checks for location services authorization status.
GetMonitoredRegions
Retrieve a list of regions that were registered to be monitored.
GetRangedRegions
Retrieve a list of beacons that are registered to be scanned
IsBluetoothEnabled
Check if Bluetooth is enabled
IsRangingAvailable
Check if the device supports scanning for beacons (ranging)
RequestAlwaysAuthorization
Prompts the user to request permissions to always use location services, even when the application is closed (on iOS); On Android, requests usage of Bluetooth and location services
RequestStateForRegion
iOS Only. Queries the state of a given region.
RequestWhenInUseAuthorization
Prompts the user to request permissions to use location services when the application is in usage; On Android, requests usage of Bluetooth and location services
StartMonitoringForRegion
Attempts to start monitoring for a provided region
StartRangingBeaconsInRegion
Attempts to start ranging for beacons on the provided region
StopMonitoringForRegion
Attempts to stop monitoring for the provided region
StopRangingBeaconsInRegion
Attempts to stop ranging for beacons on the provided region
EnableBluetooth
Android only. Prompts the user to enable Bluetooth
DisableBluetooth
Android only. Prompts the user to disable Bluetooth
Web blocks
Web Block/Description
iBeaconCentralDispatcher
This webblock is the main central for beacon events. This component should be placed on all screens where it is expected to receive events related to beacons.
The following events are available:
OnDidDetermineStateForRegion - Triggered when the state of a region is determined. Provides the region and the state upon delivery. State value is one of the following options:
CLRegionStateInside
CLRegionStateOutside
CLRegionStateUnknown
ErrorUnknownCLRegionStateObjectReceived - (Android only)
OnDidRangeBeacons - Triggered periodically when a ranging event occurs.
OnDidStartMonitoringForRegion - Triggered after a region is registered successfully to be monitored
OnEnterRegion - Triggered when the device is enters a monitored region
OnExitRegion - Triggered when the device exits a monitored region
OnMonitoringDidFailForRegionWithError - Triggered after an attempt to register a region to be monitored. Provides additional details of the error.
Beacons and Regions
A Beacon is uniquely identified by a UUID, Major and Minor. The UUID is static and is set upon manufacture while Major and Minor can usually be set using the manufacturer companion software or decided when they are bought.
A region can be composed of one or more beacons. For example, a region composed of UUID = 00000000-0000-0000-0000-000000000000 and Major 1 but no Minor specified can be composed of many beacons that contain the same UUID and Major but vary on the Minor.
Examples:
Region A with UUID = 00000000-0000-0000-0000-000000000000 and Major = 1 can have the following beacons:
UUID Major Minor
00000000-0000-0000-0000-000000000000 1 1
00000000-0000-0000-0000-000000000000 1 2
00000000-0000-0000-0000-000000000000 1 3
Usage
How do I monitor regions?
In order to monitor regions, the user has to grant permissions to access location services and Bluetooth. Decide where in the context of your application you see fit to request for permissions and use either RequestAlwaysAuthorization or RequestWhenInUseAuthorization in order to prompt the user for permissions.
Make sure to place the iBeaconCentralDispatcher WebBlock on a screen and add event listeners for OnEnterRegion and OnExitRegion in order to receive monitor events.
Next, register for one or more regions using StartMonitoringForRegion client action and, in order to receive feedback on the status of the registration, add a listener for OnDidStartMonitoringForRegion and OnMonitoringDidFailForRegionWithError on iBeaconCentralDispatcher.
Suggestion: Place the iBeaconCentralDispatcher on the Layout to make it accessible throughout the application.
How do I scan/range for beacons?
Ranging/Scanning for beacons allows the application to get detailed information about visible beacons such as RSSI (Received Signal Strength Indicator), Proximity, Accuracy, UUID, Major and Minor.
First, decide where on the context of the application you see fit to request user permission to access location services and Bluetooth and use either RequestAlwaysAuthorization or RequestWhenInUseAuthorization.
Next, make sure to place the iBeaconCentralDispatcher WebBlock on a screen and add an event listener for OnDidRangeBeacons. If the devices is near any of the beacons from the region, a list of beacons will be delivered through the OnDidRangeBeacons event.