iBeacon Sample Project

In this post I want to show you how we can create the simplest iOS app that monitors and ranges devices that follow the iBeacon protocol. An iBeacon device is a BLE (Bluetooth Low Energy) device that transmits its identification information: UUID, major and minor.
You can learn more about iBeacon in this previous post here.

The complete xcode project that is explained in this post can be downloaded from my public github repository here.


Project setup

  1. Create a new empty project in XCode. You can select the Single View Application template.
  2. Enable the permissions needed to use the Core Location services. To do this, add the following two properties in the .plist file of your app:

    NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription.

    Here is an example of these two properties:

    <key>NSLocationWhenInUseUsageDescription</key>
    <string>Location is needed to monitor Beacons in range</string>
    <key>NSLocationAlwaysUsageDescription</key>
    <string>Location is needed to monitor Beacons in range</string>
    

My Location Manager

  1. Create the class that will manage all the beacon events: MyLocationManager.
  2. Import the CoreLocation library in the .h file of your new class:
    #import <CoreLocation/CoreLocation.h>
  3. The MyLocationManager class is going to implement the CLLocationManagerDelegate protocol to receive the beacon events:
    @interface MyLocationManager : NSObject <CLLocationManagerDelegate>
  4. The MyLocationManager class also needs two methods so the app can start/stop monitoring iBeacons. Add these methods to the interface:
    
    - (void)startMonitoringUUID:(NSString *)uuid;
    
    - (void)stop;
    
    

Monitoring iBeacons

  1. Open the implementation .m file of our MyLocationManager class and add a private property to keep an instance of the iOS system CLLocationManager class.
    @interface MyLocationManager ()
    @property (strong,nonatomic) CLLocationManager *locationManager;
    @end
    
  2. Implement the start method.
    - (void)startMonitoringUUID:(NSString *)uuid
    {
        self.locationManager = [[CLLocationManager alloc] init];
        self.locationManager.delegate = self;
    
        // Request permission (mandatory iOS8 + info.plist)
        if([self.locationManager respondsToSelector:@selector(requestAlwaysAuthorization)])
            [self.locationManager requestAlwaysAuthorization];
    
        CLBeaconRegion *region = [[CLBeaconRegion alloc]
           initWithProximityUUID:[[NSUUID alloc] initWithUUIDString:uuid]
           identifier: uuid];
    
        [self.locationManager startMonitoringForRegion:region];
    }
    

    Line 3. Create an object of the CLLocationManager class.
    Line 4. Set our MyLocationManager object as its delegate.
    Line 7-8. Request permission.
    Line 10-12. Create a region with the UUID received as parameter.
    Line 14. Start monitoring for the recently created region.

  3. Implement the delegate method to receive the iBeacon events. For this small sample app, iBeacon events are just printed to the app log:
    - (void)locationManager:(CLLocationManager *)manager didDetermineState:(CLRegionState)state forRegion:(CLRegion *)region
    {
        switch (state) {
            case CLRegionStateInside:
                NSLog(@"locationManager didDetermineState INSIDE for %@", region.identifier);
                break;
    
            case CLRegionStateOutside:
                NSLog(@"locationManager didDetermineState OUTSIDE for %@", region.identifier);
                break;
    
            default:
                NSLog(@"locationManager didDetermineState OTHER for %@", region.identifier);
        }
    }
    
  4. Finally implement the stop method:
    - (void)stop
    {
        for(id region in self.locationManager.monitoredRegions) {
            [self.locationManager stopMonitoringForRegion:region];
        }
    }
    

Ranging iBeacons

  1. Add the code to start ranging. A good approach is to start ranging once it has been detected that the user is inside a region. This code is added in the locationManager:didDetermineState:forRegion method:
    - (void)locationManager:(CLLocationManager *)manager didDetermineState:(CLRegionState)state forRegion:(CLRegion *)region
    {
        switch (state) {
            case CLRegionStateInside:
                NSLog(@"locationManager didDetermineState INSIDE for %@", region.identifier);
                [self.locationManager startRangingBeaconsInRegion:(CLBeaconRegion*)region];
                break;
    
            case CLRegionStateOutside:
                NSLog(@"locationManager didDetermineState OUTSIDE for %@", region.identifier);
                break;
    
            default:
                NSLog(@"locationManager didDetermineState OTHER for %@", region.identifier);
        }
    }
    
  2. Add the code to stop ranging. A good approach is to stop ranging when it is detected that the user is outside a region. This code is added in the locationManager:didDetermineState:forRegion method:
    - (void)locationManager:(CLLocationManager *)manager didDetermineState:(CLRegionState)state forRegion:(CLRegion *)region
    {
        switch (state) {
            case CLRegionStateInside:
                NSLog(@"locationManager didDetermineState INSIDE for %@", region.identifier);
                [self.locationManager startRangingBeaconsInRegion:(CLBeaconRegion*)region];
                break;
    
            case CLRegionStateOutside:
                NSLog(@"locationManager didDetermineState OUTSIDE for %@", region.identifier);
                [self.locationManager stopRangingBeaconsInRegion:(CLBeaconRegion*)region];
                break;
    
            default:
                NSLog(@"locationManager didDetermineState OTHER for %@", region.identifier);
        }
    }
    
  3. Finally implement the delegate method to receive the iBeacon ranging events. These ranging events are just printed to the app log:
    - (void)locationManager:(CLLocationManager *)manager didRangeBeacons:(NSArray *)beacons inRegion:(CLBeaconRegion *)region
    {
        if(beacons != nil && (0 < beacons.count)) {
            for(CLBeacon *b in beacons) {
                NSLog(@"%@/%@ %ld", b.major, b.minor, b.proximity);
            }
        }
    }
    

The complete xcode project that has been explained in this post can be downloaded from my public github repository here.

Share Button

Leave a Reply

Your email address will not be published.

Time limit is exhausted. Please reload the CAPTCHA.