iOS-SDK

Introduction

Beaconstac SDK is an easy way to enable proximity marketing and location analytics through an iBeacon-compliant BLE network.

Documentation

• Please refer to the API reference.
• Tutorials and Programming guide available at http://docs.beaconstac.com/docs/references.html

Demo app

Try out the Beaconstac Demo app on the iTunes App Store.

Installation

Using Cocoapods (recommended):

Add the following to your Podfile in your project, we are supporting iOS 10.0+ make sure your pod has proper platform set.

platform :ios, '10.0'
target '<My-App-Target>''
pod 'Beaconstac', '~> 3.1'

Run pod install in the project directory

Manually:

1. Download or clone this repo on your system.
2. Drag and drop the Beaconstac.framework file into your Xcode project. Make sure that "Copy Items to Destination's Group Folder" is checked.

3. Add the Beaconstac.framework and EddystoneScanner.framework to the embedded binaries section of your destination app target.

4. In Build Phases under destination app target, add the following frameworks in Link Binary With Libraries section:

• CoreData.framework
• SystemConfiguration.framework
• CoreBluetooth.framework
• CoreLocation.framework
• EddystoneScanner.framework

Configure your project

1. In Info.plist, add a new fields, NSLocationAlwaysUsageDescription, NSLocationAlwaysAndWhenInUsageDescription, NSBluetoothPeripheralUsageDescription with relevant values that you want to show to the user. This is mandatory for iOS 10 and above.

Pre-requisite

Location

The app should take care of handling the permissions as required by your set up.

Bluetooth

The app should take care of enabling the bluetooth to range beacons.

MY_DEVELOPER_TOKEN

The app should provide the developer token while initializing the SDK. Get it from Beaconstac Dashboard Account Page.

Set Up

1. Import the framework header in your class

import Beaconstac

2. Initialize Beaconstac using one-line initialization, the initialization starts scanning for beacons immediately.

do {
    Beaconstac.sharedInstance("MY_DEVELOPER_TOKEN", completion: : { (beaconstac, error) in
      if let beaconstacInstance = beaconstac {
        // Successful...
      } else if let e = error {
        print(e)
      }
    }))
} catch let error {
    print(error)
}

3. If you want to use the advacnced integration, use iBeaconOption as defined below

iBeaconOption	Location Authorization	Monitoring	Ranging	Description
WhenInUse	When In Use Authorization	CoreLocation API doesn't support	CoreLocation API supports	App should be in the foreground
BackgroundRangeOnDisplayWakeUp	Always Authorization	CoreLocation API supports	CoreLocation API supports	App can be in the background but doesn't range

do {
    Beaconstac.sharedInstance("My_DEVELOPER_TOKEN", ibeaconOption: .BackgroundRangeOnDisplayWakeUp, delegate: self, completion: : { (beaconstac, error) in
      if let beaconstacInstance = beaconstac {
          beaconstac?.startScanningBeacons()
          // Initialization successful, it just works...
      } else if let e = error {
          print(e)
      }
    })
} catch let error {
    print(error)
}

4. If you wish to get the sharedInstance() of the Beaconstac SDK, after you initialize the Beaconstac SDK at any point in a single application life cycle

do {
    beaconstacInstance = try Beaconstac.sharedInstance()
} catch let error {
    print(error)
}

5. If you wish to control start and stop of scanning for beacons:

beaconstac.startScanningBeacons() // Starts scanning for beacons...
beaconstac.stopScanningBeacons() // Stops scanning for beacons...

6. Implement BeaconDelegate protocol methods to receive callbacks when beacons are scanned

// In the class where you want to listen to the beacon scanning events...
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.delegate = self

// required
func didFail(_ beaconstac: Beaconstac, error: Error) {
    print(error)
}

//Optional
func didEnterRegion(_ beaconstac: Beaconstac, region: String) {
    print(region)
}

func didRangeBeacons(_ beaconstac: Beaconstac, beacons: [MBeacon]) {
    print(beacons)
}

func didEnterBeacon(_ beaconstac: Beaconstac, beacon: MBeacon) {
    print(beacon)
}

func didExitBeacon(_ beaconstac: Beaconstac, beacon: MBeacon) {
    print(beacon)
}

func didExitRegion(_ beaconstac: Beaconstac, region: String) {
    print(region)
}

7. Implement RuleProcessorDelegate protocol methods to receive callbacks when rules are triggered

// In the class where you want to listen to the rule triggering events...
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.ruleDelegate = self

func willTriggerRule(_ beaconstac: Beaconstac, rule: MRule) {
    // read which rule is about to trigger and the actions, filters set by the marketers...
}

func didTriggerRule(_ beaconstac: Beaconstac, rule: MRule) {
    // read which rule is triggered and the actions, filters set by the marketers...
}

8. Implement NotificationDelegate protocol methods to override the display of the Local Notification.

// In the class where you want to listen to notification events...
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.notificationDelegate = self

func overrideNotification(_ beaconstac: Beaconstac, notification: MNotification) {
    // If you override, you should handle everything from configuring, triggering and displaying of the notification.
}

9. Implement WebhookDelegate protocol methods to add additional parameters to be sent to the webhook.

// In the class where you want to listen to webhook events...
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.webhookDelegate = self

func addParameters(_ beaconstac: Beaconstac, webhook: MWebhook) -> Dictionary<String, Any> {
    // If you override, make sure the keys of the previously added
}

10. The Latch_Latency, defines how the campOn/campOff behaviour is adjusted when the SDK finds the beacon. Lets say, the SDK camped on to a beacon and there is a beacon who's latest RSSI, is less than the latest RSSI of the camped On beacon + the latch latency, then SDK camps off from the current beacon and camps on to this beacon.

beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.latchLatency = HIGH

11. If you don't listen to the NotificationDelegate protocol, the SDK configures, triggers UNNotification. However to present the notification do the following.

// Check if the notification is from SDK and provide UNNotificationPresentationOptions or nil by invoking the below method.
public func notificationOptionsForBeaconstacNotification(_ notification: UNNotification) -> UNNotificationPresentationOptions?


// EXAMPLE:
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    var notificationPresentationOptions: UNNotificationPresentationOptions
    if let notificationOption = try! beaconstac.sharedInstance().notificationOptionsForBeaconstacNotification(notification) {
      notificationPresentationOptions = notificationOption
    } else {
      // My Presenation options...
    }
    completionHandler(notificationPresentationOptions)
}



// Check if SDK can handle the notification by invoking the below method.
public func showCardViewerForLocalNotification(_ notification: UNNotification) -> Bool


// EXAMPLE:
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    if beaconstac.showCardViewerForLocalNotification(notification) {
        // We will handle the notification...
    } else {
        // Handle it...
    }
    completionHandler()
}

12. You are required to add filters regarding the app user, if the marketer has provided the filters. To do so

// Provide the filters to the SDK as Key-Value pairs using dictionary. Note keys are case insensitive.
func addFilters(_ filters: Dictionary<String, Any>)

Note: If the rule contains the filters and app doesn't provide it, the rule will be treated as a filter validation failed and we won't trigger that particular rule.

13. The SDK collects analytics regarding how we collect the iBeacon related information and tie it to app user(MVisitor). If you know information about your app user, create a MVisitor object and provide it to us.

// If you know the your app visitor, create a Visitor object and call this on the Beaconstac instance.
func setVisitor(_ visitor: MVisitor)