When you start working with iBeacons, first check if all required Beacon information is available. These are the Beacon major ID and your the Beacon UUID. Both can be found in the xamoom CMS, just open Markers and select any of your listed markers. Now you can see your app related Beacon UUID and major ID.

For Monitoring & Ranging iBeacons you need CLLocationManager, CLLocation and CLBeaconRegion. Also check Apple Programming Guide for Location & Maps.

Setup

The SDK handles the Beacon and the user location logic in the LocationHelper class automatically. For using the this class, create a helper class like this.

class Helper: NSObject {
   static let shared = Helper()
   let locationHelper: LocationHelper = LocationHelper(beaconRegion: BEACON_UUID, beaconMajor: BEACON_MAJOR, beaconIdentifier: BEACON_IDENTIFIER, api: XMMEnduserApi(apiKey: "ApiKey"))
}

In the constructor of LocationHelper, enter your Beacon related information and also a XMMEnduserApi. This is required because LocationHelper starts downloading content items if beacons are ranged.

Usage

To start ranging for beacons and start monitoring the user location, implement the following lines in your AppDelegates applicationWillEnterForeground function like this.

let locationHelper = Helper.shared.locationHelper
locationHelper?.startLocationUpdateing()

After starting the user location monitoring and the beacon ranging you have to implement a NotificationCenter observer for handling ranged beacons. There are multiple observers that can be triggered.

LOCATION_UPDATE

This Observer triggers when a new user location is detected.

NotificationCenter.default.addObserver(self, selector: #selector(didUpdateLocation(notification:)),
                   name: NSNotification.Name(rawValue: LOCATION_UPDATE),
                   object: nil)

...

func didUpdateLocation(notification: NSNotification) {
   let userLocation = notification.userInfo?["location"] as? CLLocation
}

BEACON_ENTER

This Observer triggers when the user enters a new CLRegion.

NotificationCenter.default.addObserver(self, selector: #selector(didEnterRegion(notification:)),
                   name: NSNotification.Name(rawValue: BEACON_ENTER),
                   object: nil)

...

func didEnterRegion(notification: NSNotification) {
   let region = notification.userInfo?["region"] as? CLRegion
}

BEACON_EXIT

This Observer triggers when the user leaves a CLRegion.

NotificationCenter.default.addObserver(self, selector: #selector(didExitRegion(notification:)),
                   name: NSNotification.Name(rawValue: BEACON_EXIT),
                   object: nil)

...

func didExitRegion(notification: NSNotification) {
   let region = notification.userInfo?["region"] as? CLRegion
}

BEACON_RANGE

This Observer triggers when beacons are ranged.

NotificationCenter.default.addObserver(self, selector: #selector(didRangeBeacons(notification:)),
                   name: NSNotification.Name(rawValue: BEACON_RANGE),
                   object: nil)

...

func didRangeBeacons(notification: Notification) {
   var beacons: [CLBeacon] = []
    
   if let items = notification.userInfo?[XAMOOM_BEACONS_KEY] {
      beacons = items as! [CLBeacon]
   }
}

BEACON_CONTENTS

This Observer triggers when beacons are ranged and content items for the beacons minor IDs are connected.

NotificationCenter.default.addObserver(self, selector: #selector(didRangeBeaconContents(notification:)),
                   name: NSNotification.Name(rawValue: BEACON_CONTENTS),
                   object: nil)

...

func didRangeBeaconContents(notification: Notification) {
   if let userInfo = notification.userInfo {
      let beaconContents = userInfo[XAMOOM_CONTENTS_KEY] as! [XMMContent]
    }
}

Avoid same Beacons

To avoid issues when ranging beacons, because you monitored the same beacon again or multiple times set the LocationHelpers filterSameBeaconScans property to true. The Observer only triggers if the new ranged beacons are not the same as before.

locationHelper?.filterSameBeaconScans = true

Background Location Updates

You are also able to update the user location when the device is in background. For this read Handling Location Events in the Background in the Apple Developer Documentation.

After you enabled the location background mode, you have to implement following lines in your AppDelegates didFinishLaunchingWithOptions.

if let keys = launchOptions?.keys {
   if keys.contains(.location) {
      locationHelper?.stopLocationUpdating()
      locationHelper?.startLocationUpdateing()
   }
}

Next Step

• Show Beacon Notifications