Working with iBeacons
In this tutorial, the concept, API and usage of Beacon APIs available in IBM MobileFirst Platform Foundation are discussed in the context of native iOS applications.
The following topics are covered:
- Registering Beacons
- Registering Beacon Triggers
- Associating Beacons and Beacon Triggers
- Server side API
- Application configuration steps
- Simplified APIs for ranging/monitoring of iBeacons
- Sample application
Beacons are represented as
Beacon objects in IBM MobileFirst Platform. Beacons are identified using UUID, major and minor values. The UUID in its canonical form is represented by 32 lowercase hexadecimal digits. The major and minor values are positive numbers in range of 0-65535 (inclusive).
Beacon objects also contains a field
customData which is a JSON payload representing customer-specific data representing the beacon. For example, the store/location where the beacon is deployed.
Beacons can be registered / updated / deleted using REST APIs. For detailed information on the REST APIs, refer the REST Services API in the IBM MobileFirst user documentation topics.
Register the following beacons using the Beacons (PUT) REST API
Registering Beacon Triggers
Beacon triggers are represented as
BeaconTrigger objects in IBM MobileFirst Platform. Beacon Triggers are identified by a triggerName and contain triggerType, proximityState, dwellingTime (optional) and actionPayload.
triggerType can take any of the following values:
|Enter||The trigger is activated when the device enters the associated beacon region|
|Exit||The trigger is activated when the device leaves the associated beacon region|
|DwellInside||The trigger is activated when the device remains inside the associated beacon region for a given time period|
|DwellOutside||The trigger is activated when the device remains outside the associated beacon region for a given time period|
|Immediate||The proximity of the device to this beacon region should be "immediate" (physically very close) for the trigger to be activated|
|Near||The proximity of the device to this beacon region should be at least "near" (approximately 1-3 meters) for the trigger to be activated|
|Far||The proximity of the device to this beacon region should be at least "far" for the trigger to be activated|
dwellingTime is applicable only for triggerTypes: "DwellInside" and "DwellOutside". It should be specified in milliseconds and defines how long the device must be inside, or outside a beacon region before the dwellInside or dwellOutside trigger is activated. Mandatory with triggerType of "DwellInside" and "DwellOutside"
actionPayload represents the details of the action to be taken when trigger is activated
Beacon triggers can be registered / updated / deleted using REST APIs. For detailed information on the REST APIs, refer the REST Services API in the IBM MobileFirst user documentation topics.
Register the following beacon triggers using the Beacon Triggers (POST) REST API.
Associating Beacons and Beacon Triggers
An association between a beacon and a beacon trigger is represented as
BeaconTriggerAssociation object in IBM MobileFirst Platform. The association can be created / updated / deleted using REST APIs. For detailed information on the REST APIs, refer the REST Services API in the user documentation topics
Creating the association between beacons and triggers for an application can be achieved using the Associate beacons and triggers (PUT) REST API:
Retrieving beacons and triggers - Server side API
Retrieving beacons, triggers and their associations can be achieved by using
WL.Server.getBeaconsAndTriggers(applicationName, beaconsOfInterest) API
applicationName– is the name of the MobileFirst application
beaconsOfInterest– is a JSON block or an array of JSON blocks identifying the beacon(s) whose trigger associations have to be fetched.
Application configuration steps
Allowing the application to do ranging/monitoring for iBeacon regions can be achieved by selecting the following background modes:
|Location updates||Ensures the application gets callbacks when device enters/exits iBeacon regions.|
|Uses Bluetooth LE accesssories||Ensures the application can do ranging for iBeacons|
|Acts as a Bluetooth LE accessory||Enables the device to act as an iBeacon.|
|External accessory communication||Enables the application to communicate with accessories attached to the device.|
On iOS 8 and above, to enable Location services, add
NSLocationAlwaysUsageDescription in native iOS project's Info.plist.
Copy the "iOSNativeiBeaconsLibrary" folder in the iOSNativeiBeacons project into your native iOS application. This contains the library that provides the simplified set of APIs for ranging/monitoring of iBeacons.
Requesting permission to use location services and local/push notifications can be achieved by:
Simplified APIs for ranging/monitoring of iBeacons
Loading beacons and triggers from server
Loading beacons information, triggers and their associations from server and storing it in the application JSONStore can be achieved by:
Monitoring/ranging of iBeacons and firing of trigger actions can be achieved using:
If the user wishes to opt out of iBeacon monitoring, it can achieved using:
Turn the device to an iBeacon
Turning the device into an an iBeacon can be achieved using:
This is generally for testing /development purpose. The UUID string here should match the UUID of beacons registered on server.
Increasing application running time
Increasing the running time of the application when in background (as part of iBeacon monitoring) can be achieved using:
This increases the running time of the application up to 3 minutes from the default 10 seconds.
Handling local notifications
Handling local notifications originating from the application can be achieved by:
The sample contains two projects:
- The iBeaconsNativeProject.zip file contains a MobileFirst native API that you can deploy to your MobileFirst server.
- The iOSNativeiBeaconsProject.zip file contains a native library that provides a simplified set of APIs for ranging/monitoring of iBeacons and a native iOS application that demonstrates the usage of those APIs.
Make sure to update the worklight.plist file in iOSNativePush with the relevant server settings.
The sample showcases a simple banking scenario where actions are triggered based on proximity:
- When the user enters a Bank branch, a notification action is triggered with a Welcome message
- When the user stays in the Bank branch, an alert is triggered with a message stating that a bank personnel will assist the user soon
- When the user exits the Bank branch, a notification action is triggered with a message