Working with iBeacons

improve this page | report issue

Overview

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

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

{
    "uuid": "3d402cf0-3691-4bd9-97ff-0b0a93a160ef",
    "major": 1,
    "minor": 4417,
    "customData": {
        "branchName": "Indiranagar, Bangalore"
    }
}

{
    "uuid": "3d402cf0-3691-4bd9-97ff-0b0a93a160ef",
    "major": 2,
    "minor": 4417,
    "customData": {
        "branchName": "Koramangala, Bangalore"
    }
}

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:

Trigger Type Description
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
proximityState can take any of the following values (Default value: Far):

Proximity State Description
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.

{
    "triggerName": "entryIntoBranch",
     "triggerType": "Enter",
     "proximityState": "Near",
     "actionPayload": {
        "alert": "Welcome to $branchName branch of IMF Bank"
     }
 }

{
    "triggerName": "dwellInsideBank",
     "triggerType": "DwellInside",
     "dwellingTime": 5000,
     "proximityState": "Near",
     "actionPayload": {
        "alert": "You will be assisted soon by our staff."
     }
 }

{
    "triggerName": "exitFromBranch",
     "triggerType": "Exit",
     "proximityState": "Far",
     "actionPayload": {
        "alert": "Thank you for visiting our $branchName branch. Have a nice day!"
     }
 }

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:

{
    "beacons": [
        {
            "uuid": "3d402cf0-3691-4bd9-97ff-0b0a93a160ef",
            "major": 1,
            "minor": 4417
        },
        {
            "uuid": "3d402cf0-3691-4bd9-97ff-0b0a93a160ef",
            "major": 2,
            "minor": 4417
        }
    ],
    "triggers": [
        {
            "triggerName": "entryIntoBranch",
            "triggerName": "exitFromBranch",
            "triggerName": "dwellInsideBank"
        }
    ]
}

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:

missing_alt

Background modes Description
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.

missing_alt

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:

- (void) viewDidLoad {
	[super viewDidLoad];
	...
	[[WLBeaconsLocationManager sharedInstance] requestPermissionToUseLocationServices];
	[[WLBeaconsLocationManager sharedInstance] requestPermissionToUseNotifications];
}

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:

[[WLBeaconsAndTriggersJSONStoreManager sharedInstance] loadBeaconsAndTriggersFromAdapter:@"iBeaconsAdapter" withProcedure:@"getBeaconsAndTriggers" withCompletionHandler:^(bool success, NSString *error) {
	if (success) {
		[self showBeaconsAndTriggers];
	} else {
		[self updateView:error];
	}
}];


Triggering actions

Monitoring/ranging of iBeacons and firing of trigger actions can be achieved using:

	[[WLBeaconsLocationManager sharedInstance] startMonitoring];

If the user wishes to opt out of iBeacon monitoring, it can achieved using:

	[[WLBeaconsLocationManager sharedInstance] stopMonitoring];
	// Optionally reset monioring/ranging state
	[[WLBeaconsLocationManager sharedInstance] resetMonitoringRangingState]; 


Turn the device to an iBeacon

Turning the device into an an iBeacon can be achieved using:

	NSString *uuidString = @"3d402cf0-3691-4bd9-97ff-0b0a93a160ef";
	int major = 1;
	int minor = 4417;
	[[WLBeaconsLocationManager sharedInstance] turnIntoiBeaconWithUuid:uuidString withMajor:major withMinor:minor withStatusHandler:^(NSString *turnIntoiBeaconStatusDetails) {
		[self updateView:turnIntoiBeaconStatusDetails];
	}];

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:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	...
	[[WLBeaconsLocationManager sharedInstance] notifyApplicationDidFinishLaunchingWithOptions];
}</p>
<p>- (void)applicationDidEnterBackground:(UIApplication *)application {
	...
	[[WLBeaconsLocationManager sharedInstance] notifyApplicationDidEnterBackground];
}</p>
<p>- (void)applicationDidBecomeActive:(UIApplication *)application {
	...
	[[WLBeaconsLocationManager sharedInstance] notifyApplicationDidBecomeActive];
}
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:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	...
	UILocalNotification *localNotif = [launchOptions objectForKey:UIApplicationLaunchOptionsLocalNotificationKey];
	if (localNotif) {
		application.applicationIconBadgeNumber = application.applicationIconBadgeNumber - 1;
		[self processLocalNotification:localNotif];
	}
	return YES;
}</p>
<p>- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
	application.applicationIconBadgeNumber = application.applicationIconBadgeNumber - 1;
	[self processLocalNotification:notification];
}</p>
<p>- (void)processLocalNotification:(UILocalNotification *)notification
{
	NSString *alertMessage = [notification.userInfo objectForKey:@"alertMessage"];
	UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Received local notification" message:alertMessage delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil, nil];
	[alert show];
}

Sample application

Click to download the Studio project. Click to download the Native project.

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

missing_alt

missing_alt

missing_alt

Last modified on November 09, 2016