Support iBeacons In Your Ionic Framework Mobile App

I recently picked up some Estimote iBeacons to play around with and figured I’d try to get them working in an Ionic Framework Android and iOS application.

If you’re unfamiliar with iBeacons, they are small bluetooth proximity devices. There are many different manufacturers, but Estimote appears to have the best advertised battery life and durability. iBeacons generally broadcast a signal every 100ms to 1000ms depending on the configuration or brand. The broadcast signal contains a UUID and two numeric identifiers which are a major and minor version.

Before I get into the code I’ll share a few possible use cases for iBeacons:

1. Triggering some literature or audio when your device detects that you’re near a particular iBeacon in a museum. Put one near The Statue of David in Italy and bam, you could have information about it when you approach it.
2. Tracking foot traffic in your store. Maybe you have a large store like Walmart with iBeacons in every department. You can see which department gets the most traffic.
3. Calculating how long time-wise a queue / line is for a particular ride at an amusement park based on device to beacon discovery.

There are endless other useful scenarios.

Alright so you know a bit more about iBeacons, now it is time to get into the code. Assuming you already have Ionic configured on your machine, from the Terminal or Command Prompt run the following commands:

ionic start IonicBeacon blank
cd IonicBeacon
ionic platform add ios
ionic platform add android

If you are not using a Mac, do not try to add and build for the iOS platform. Only Android will work on Linux and Windows machines.

The plugin we’re going to use for iBeacons is cordova-plugin-ibeacan by Peter Metz. At the time of writing this tutorial, I am using the latest version which is commit 50315dbc. If you want to be adventurous and see if a newer version works, that is up to you.

With IonicBeacon as the working directory of your Terminal or Command Prompt, run the following to install the plugin:

cordova plugin add https://github.com/petermetz/cordova-plugin-ibeacon.git

We are almost ready to start coding. The iBeacon plugin by Peter Metz is plain JavaScript and doesn’t work the best with Ionic out of the box. Instead, we’re going to use the AngularJS wrapper I wrote for this plugin. The wrapper ng-cordova-beacon can be found on my GitHub page. Download ng-cordova-beacon.min.js from the dist directory and drop it in your project’s www/js directory.

Next up, open your project’s www/index.html file and include the following JavaScript file above the app.js line:

<script src="js/ng-cordova-beacon.min.js"></script>

With the AngularJS wrapper included, open your project’s www/js/app.js file and include the following code:

angular.module('starter', ['ionic', 'ngCordovaBeacon'])

.run(function($ionicPlatform) {
    $ionicPlatform.ready(function() {
        if(window.cordova && window.cordova.plugins.Keyboard) {
            cordova.plugins.Keyboard.hideKeyboardAccessoryBar(true);
        }
        if(window.StatusBar) {
            StatusBar.styleDefault();
        }
    });
})

.controller("ExampleController", function($scope, $rootScope, $ionicPlatform, $cordovaBeacon) {

    $scope.beacons = {};

    $ionicPlatform.ready(function() {

        $cordovaBeacon.requestWhenInUseAuthorization();

        $rootScope.$on("$cordovaBeacon:didRangeBeaconsInRegion", function(event, pluginResult) {
            var uniqueBeaconKey;
            for(var i = 0; i < pluginResult.beacons.length; i++) {
                uniqueBeaconKey = pluginResult.beacons[i].uuid + ":" + pluginResult.beacons[i].major + ":" + pluginResult.beacons[i].minor;
                $scope.beacons[uniqueBeaconKey] = pluginResult.beacons[i];
            }
            $scope.$apply();
        });

        $cordovaBeacon.startRangingBeaconsInRegion($cordovaBeacon.createBeaconRegion("estimote", "b9407f30-f5f8-466e-aff9-25556b57fe6d"));

    });
});

Let’s break down what is happening here.

angular.module('starter', ['ionic', 'ngCordovaBeacon'])

First we need to inject ng-cordova-beacon into the AngularJS module. With that added we can proceed to using it in our controller.

Since the plugin uses native device code we need to wrap any calls to it in an $ionicPlatform.ready before we try to use it. For iOS only we are requesting permission to use location services. On Android this request will be ignored because it isn’t necessary.

In the $rootScope.$on call we are listening for ranging hits. Basically we are checking if the iBeacon is in range and how far it is. If the broadcast is found, add the found beacon to an object that we can use on the front-end view.

Finally we are starting to range for a region of beacons. You can call this as many times as you want for different sets, but I’m just ranging for one set of beacons. The one set being the following:

$cordovaBeacon.createBeaconRegion("estimote", "b9407f30-f5f8-466e-aff9-25556b57fe6d")

I chose to use estimote as a human readable identifier for the UUID that follows. You can optionally include a major and minor version, but by leaving them out you are using a wildcard. You can have multiple majors and minors per UUID so by leaving them off, you may get many results.

The final thing to worry about is how this app is going to look. Going back to the project’s www/index.html file, add the following code between the <ion-content> tags:

<ion-content ng-controller="ExampleController">
    <div class="list">
        <div class="item" ng-repeat="(key, value) in beacons">
            <div class="row">
                <div class="col truncate">
                    {{value.uuid}}
                </div>
            </div>
            <div class="row">
                <div class="col">
                    major: {{value.major}}
                </div>
                <div class="col">
                    minor: {{value.minor}}
                </div>
            </div>
            <div class="row">
                <div class="col">
                    {{value.proximity}}
                </div>
            </div>
        </div>
    </div>
</ion-content>

I’m using a class Ionic doesn’t include called truncate which we need to add. Open your project’s www/css/style.css and add the following:

.truncate {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
}

We’re using this so our very long UUID values don’t float off the screen. Instead they will be gracefully clipped if they are too long.

Above is what the application should look like when it has detected iBeacons.

Conclusion

You can do a lot of cool things with iBeacons and they aren’t difficult to use with Ionic Framework. You can pick up a developer kit from Estimote, which includes several beacons compatible with both Android and iOS.

A video version of this article can be seen below.

Nic Raboy

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in C#, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Unity. Nic writes about his development experiences related to making web and mobile development easier to understand.