Estimote Proximity SDK for iOS

Estimote Proximity SDK aims to provide a simple way for apps to react to physical context by reading signals from Estimote Beacons. It uses Core Bluetooth and Core Location frameworks to provide the best beacon-based experience possible.

Note: this project was previously known as Estimote SDK 5.0.0.

1. Reliability. It's built upon Estimote Monitoring, Estimote's algorithm for reliable enter/exit reporting.
2. No need to operate on abstract identifiers, or Proximity UUID, Major, Minor triplets. Estimote Proximity SDK lets you define zones by setting predicates for human-readable JSONs.
3. You can define multiple zones for a single beacon, i.e. at different ranges.
4. Cloud-backed grouping. When you change your mind and want to replace one beacon with another, all you need to do is reassign JSON attachments in Estimote Cloud. You don't even need to connect to the beacon!

CocoaPods is an easy way to add external libraries. To use it to fetch Proximity SDK:

1. Add pod 'EstimoteProximitySDK' to your Podfile

2. Run pod install --repo-update

3. Make sure Always Embed Swift Standard Libraries build setting is set to Yes (this option is turned off by default for Objective–C projects). Estimote Proximity SDK contains Swift code internally and requires Swift standard libraries in the app bundle.

4. Add import EstimoteProximitySDK (Swift) or #import <EstimoteProximitySDK/EstimoteProximitySDK.h> (Objective–C) to your code

1. Download Proximity SDK repository

   • Click the "Download ZIP" button in this repo, or
   • Run git clone [email protected]:Estimote/iOS-Proximity-SDK.git --depth=1

2. Download Bluetooth Scanning library repo

   • Click the "Download ZIP" button in Bluetooth Scanning repo, or
   • Run git clone [email protected]:Estimote/iOS-Bluetooth-Scanning.git --depth=1

3. Drag & drop EstimoteProximitySDK.framework to your project (enable the checkbox in Options > Copy files if needed)

4. Drag & drop EstimoteBluetoothScanning.framework to your project (enable the checkbox in Options > Copy files if needed)

5. Add Estimote Proximity SDK to your Xcode project's Build Phases > Embed Frameworks. If this build phase isn't visible you can add the SDK in General -> Embedded Binaries section.

6. Add Estimote Bluetooth Scanning library to your Xcode project's Build Phases > Embed Frameworks. If this build phase isn't visible you can add the SDK in General -> Embedded Binaries section.

7. Make sure Always Embed Swift Standard Libraries build setting is set to Yes (this option is turned off by default for Objective–C projects). Estimote Proximity SDK contains Swift code internally and requires Swift standard libraries in the app bundle.

8. Add import EstimoteProximitySDK (Swift) or #import <EstimoteProximitySDK/EstimoteProximitySDK.h> (Objective–C) to your code

• One or more Estimote Proximity or Location Beacons configured for Estimote Monitoring. It's enabled by default in dev kits shipped after mid-September 2017; to enable it on your own check out the instructions.
• An iOS device with Bluetooth Low Energy running iOS 10 or later. Using BLE with iOS Simulator isn't supported.

The library is compatible with both Objective–C and Swift. The public-facing classes are written in Objective–C, the API is optimized for Swift. It's distributed as a dynamic framework.

Details of each of your Estimote devices are available in Estimote Cloud. Each device has a unique identifier, but remembering it and using it for every one of your devices can be challenging. This is why Estimote Proximity SDK uses attachment-based identification.

Each device has an associated JSON. When the SDK detects a proximity change of a device, it checks the device's attachment JSON to see which registered rule should be applied.

To get a working prototype, check out the Desk Observer example app. It's a single screen app with three labels that change background color:

• when you are in close proximity to the first desk,
• in close proximity to the second desk,
• when you are in the venue in general.

The demo requires at least two Proximity or Location beacons configured for Estimote Monitoring.

The demo expects beacons having specific tags assigned:

• {"attachment":{"desk":"blueberry","venue":"office"}} for the first one,
• {"attachment":{"desk":"mint","venue":"office"}} for the second one.

These attachments can be used to define the zones presented below:

Attachment-based zones

To conifgure the attachments:

1. Go to https://cloud.estimote.com/#/
2. Click on the beacon you want to configure
3. Click Settings button
4. Click Beacon Attachment field
5. Add any attachment key-value pair you want
6. Click Save Changes

Tags are Cloud-only settings — no additional connecting to the beacons with the Estimote app is required!

Assigning beacon attachments

To use the SDK within your app, go to the apps section in Estimote Cloud. Register a new app or use one of the available templates to obtain App ID & App Token credentials pair.

In your app, set up the credentials using ESTCloudCredentials:

let credentials = EPXCloudCredentials(appID: "your-app-id", appToken: "your-app-token")

Then, configure proximity discovery with EPXProximityObserver. For more info on attachments, see this section.

// Create observer instance
self.proximityObserver = EPXProximityObserver(credentials: credentials, errorBlock: { error in
    print("Ooops! \(error)")
})


// Define zones
let blueberryZone = EPXProximityZone(range: EPXProximityRange.custom(meanTriggerDistance: 0.5)!,
                                     attachmentKey: "desk",
                                     attachmentValue: "blueberry")
blueberryZone.onEnterAction = { attachment in
    print("Entered near range of 'desk':'blueberry'. Attachment payload: (attachment.payload)")
}
blueberryZone.onExitAction = { attachment in
    print("Exited near range of 'desk':'blueberry'. Attachment payload: (attachment.payload)")
}

// ... etc. You can define as many zones as you need.

// Start proximity observation
self.observer.startObserving([blueberryZone])

To allow your app to react to physical context when it's in the background:

• Set Uses Bluetooth LE accessories in your Xcode project settings -> Capabilities -> Background Modes. It's required for Core Bluetooth to work in the background.
• Add a value for Privacy - Location Always Usage Description key in your app's Info.plist file. It will be the message of an alert that will be shown to the user when the app calls -[EPXProximityObserver start...]. It's required for Core Location to work.