ABSTRACT

The App demo “iBKS Hello World” is a project that contains the most important functions to begin interacting with a Beacon.

AUDIENCE

This document is focused for App developers who have no experience in beacon communication management.

1. Before you start
2. Project iBKS Hello World
3. App permission
   1. Location
   2. Bluetooth
   3. Local Notifications
4. Scan Bluetooth devices
5. Notifications
6. Background Scan

1.Before you start

All you need to start playing with “iBKS Hello World”:

• XCode 7 or higher
• iOS device with OS version 9.0 or above and BLE capabilities.
• At least one iBKS Beacon
• Download iBKS Hello World project

2. Project iBKS Hello World

After downloading de “iBKS Hello World” project, you only have to open it on XCode, sign it with oyur developer provisioning and compile it. There are no extra libraries or steps you have to include.
The project is structured to show three important functionalities, each one on a different class:

• ScanViewController: scans and list the beacons that are advertising around and allows discovering services and characteristics. Services and characteristics will be printed in the XCode Output console. CoreBluetooth is used for this demo.
• NotificationsViewController: Show a notification dialog on the App triggered by a specific beacon packet detected. Also includes the settings view which allows you to configure the parameters in the beacon the device is looking for. CoreLocation is used for this demo.
• Background Monitoring (from AppDelegate): Starts background monitoring and ranging for beacons in a region and does some actions when detects them (send notification, open the app, …) even when the app is stopped. Background monitoring starts when APP goes to background and stops when APP comes to foreground. CoreLocation is used for this demo.

 

3. App permissions

Several permissions and requests are needed for this sample. Bluetooth and Location will be used for beacons scanning and ranging in foreground, and Local Notifications for the background monitoring in order to notify the user.

3.1. Location

In order to allow location in both foreground and background running mode, it is necessary to add the key “Privacy – Location Always Usage Description” in the Info.plist file. It should look like this:

Also request for location permissions in the AppDelegate in the “didFinishLaunchingWithOptions” method like thos:

locationManager = CLLocationManager()
locationManager!.requestAlwaysAuthorization()

3.2. Bluetooth

The only step you should do in order to properly make Bluetooth work for this sample is enable the “Location updates” and “Uses Bluetooth LE accessories” in the Background Modes for the app Capabilities. This is needed only for the background feature.

Note that even if the CoreLocation and CoreBluetooth works properly for foreground scanning and ranging in this sample, if you plan to publish your app, adding some more privacy and usage keys for Bluetooth in the Info.plist file will be required. Please check the Apple Developers guide for more information.

The app capabilities should look like this (everything else is disabled):

3.3. Local Notifications

Request for Local Notifications is also requested in the AppDelegate inside the “didFinishLaunchingWithOptions” method right after the location permission with the following code:

let notificationSettings = UIUserNotificationSettings(types: [.sound, .alert], categories: nil)
UIApplication.shared.registerUserNotificationSettings(notificationSettings)

Same as for Bluetooth, Local Notification Usage description key may be needed in the Info.plist file if the app has to be published in the App Store.

4. Scan Bluetooth devices

All the needed functions used to scan Bluetooth devices are in ScanViewController. The steps to achieve that are:

1. Implement the CBCentralManagerDelegate in the ScanViewController
2. Define and start a CBCentralManager from “viewDidLoad” method. Assign delegate self to the central manager
3. When “.poweredOn” state is received in the “centralManagerDidUpdateState” method (which is necessary for the
   CBCentralManagerDelegate), scan can be started.
4. Scanned devices will be received in the “centralManager – didDiscover peripheral” method. Treat them properly according to your needs.
5. Optionally, connect to the device. In the project, the connection is made when a device of the list is clicked.
6. For the connection, CBPeripheralDelegate and its methods are needed.
   Once the connection starts, the status will be received in the “centralManager – didConnect” method. Then service and characteristics discovery can be started. For this feature all the steps are logged in the Output console in XCode.

 

The app shows a list of all Bluetooth devices detected with its own (and sorted by) RSSI, name and assigned UUID.

5. Notifications

In some cases, it’s useful to show a notification to the user when a specific beacon is detected in a particular distance range. This example is shown in NotificationsViewController. CoreLocation is used for this sample.

iOS only allow ranging for a limit of 20 devices. Set the parameters (UUID, Major, Minor, Range and Message) for the beacon you want to detect, define its region and stare ranging with CoreLocartion. These are the steps.:

1. Define the beacon region, with the UUID, Major and Minor of your beacon.
2. Start ranging for that region and wait for the beacon to be detected.
3. Once detected, check if it is close enough and the distance matches with the
   range you defined in the settings.
4. If the range matches for our region, show a dialog with the defined
   message also in settings.

6. Background Scan

Another interesting function is the background scan. This one allows to monitor the beacons in background even if the app is killed. Simple ranging is not allowed directly in background but there is a simple way to make it work.

iOS is able to monitor for a region (beacon) even if the app has been killed. It will report in “didEnterRegion” method when the beacon is detected (it can take up to 5 seconds) and it will only occur when the state switches from outside to inside the region.

It will also report in “didExitRegion” method when the beacon is not detected anymore for some time. This detection can take from 15sec. to 5min. in order to avoid false detections. This state will occur only when switching from inside to outside region.

Also, there is a “didDetermineState” method, which it is more useful as it reports the actual state and not only when switching states. It is the method used in this example. Also it is more safe to use in background according to Apple documentation.

All the background methods used for the CoreLocation are defined and delegate in the AppDelegat. For this sample, background monitoring is started in the “applicationDidEnterBackground” (and only if the switch in MainViewController is turned ON) and it will be stopped on the method “applicationWillEnterForeground”

When a beacon is detected in background by the OS, this will wake the APP for a max. period of 10 seconds in order to process any task needed. In this case, the task will be ranging the beacon in order to check its proximity and show, if necessary, a local notification. Note that as the ranging can take only 10 seconds max., if the beacon is not ranged properly or the proximity does not match the one set in settings, the notification won’t be shown, but the state will be switched anyway to inside region.