Estimote Proximity SDK - iOS

Stick an Estimote Beacon at your desk, in your car, or on a package, and the Estimote Proximity SDK will let your app know when you enter or exit its range. Works indoors, in the background, and is accurate up to a few meters.

Powered by Estimote Monitoring: Estimote’s own signal-processing technology, with emphasis on maximum reliability. (up to 3 times better than other beacon-based technologies we’ve benchmarked against)

Other Proximity SDK highlights include:

1. Tag-based identification: define your proximity zones with human-readable tags instead of abstract identifiers.
2. Multiple zones per beacon: set up more than one enter/exit zone per single beacon. (e.g., a “near” zone and a “far” zone)
3. Software-defined range: define the enter/exit trigger range in code, rather than by the beacon’s broadcasting power.
4. Cloud-based tagging & grouping: add, remove, and replace beacons, without changing the app’s code - just modify the tags in Estimote Cloud.

Table of contents

• Tag-based identification
• Installation
• Use it in your app
  • Setting up tags
  • Inside your app
• (Optional) Adding attachments to your beacons
• Location and Bluetooth permissions, Background support
• Additional features
• Example apps
• Documentation
• Your feedback and questions
• Changelog

Tag-based identification

Estimote Proximity SDK uses tag-based identification to allow for dynamic setup changes. You monitor beacons by tags, which you assign in Estimote Cloud. For example, instead of saying:

"monitor for beacon 123 and beacon 456"

you say:

"monitor for beacons tagged as lobby".

This way, if you need to replace or add more beacons to the lobby, you just add/change tags in Estimote Cloud. Your app will pick up the new setup the next time the EPXProximityObserver is started.

Important! As our SDK is still in version 0.x.x, we're constantly modifying our API according to your feedback. Our latest iteration has evoloved our SDK to be based on simple tags, backed up with attachments as an optional additional information.

Key components

Estimote Proximity SDK is built on top of three key components: observer, zone, and zone's context. If you used previous versions of Proximity SDK you should be familiar with all of them except last one.

• Observer - responsible for starting and stopping monitoring for a provided list of zones,
• Zone - a representation for a physical space combining group of beacons with same tag.
• Zone’s context - a combination of a single beacon with its tag and list of attachments assigned to it.
• Actions (callbacks) - every zone has three types of callbacks triggered when you: enter a zone's context, exit it, or number of heard contexts changes.

Below there's a presentation of two zones:

• blueberry zone with two zone's contexts,
• mintzone with only one zone's context.

Tag-based zones

Installation

Swift compatibility

Starting with version 1.2.0 Proximity SDK supports Swift 4.2.

Swift Package Manager

Follow the article about Adding Package Dependencies to Your App using the following repository URL: https://github.com/Estimote/iOS-Proximity-SDK.

CocoaPods

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

Manual

1. Download Proximity SDK repository
   • Click the Download ZIP button in this repo, or
   • Run git clone [email protected]:Estimote/iOS-SDK-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

Use it in your app

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.

Requirements

• One or more Estimote Proximity Beacons with Estimote Monitoring enabled. Here’s how to enable it.
• An iOS device with Bluetooth Low Energy running iOS 10 or later. Using BLE with iOS Simulator isn't supported.
• An Estimote Cloud account.

Setting up tags

To configure the tags:

1. Go to https://cloud.estimote.com/#/
2. Click on the beacon you want to configure
3. Click Edit Settings button
4. Click Tags field and a drop down list with (if applicable) existing tags.
5. Either click Create New Tag at the bottom of the list and enter a name or select a tag (as many as you want/have).
6. Click Save Changes

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

Assigning beacon tags

Inside your app

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 CloudCredentials:

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

Then, configure proximity discovery with ProximityObserver. For more info on tags, see this section or documentation.

// Create observer instance
self.proximityObserver = ProximityObserver(credentials: credentials, onError: { error in
    print("Oops! \(error)")
})
// Define zones
let blueberryZone = ProximityZone(tag: "blueberry", range: ProximityRange.near)
blueberryZone.onEnter = { zoneContext in
    print("Entered near range of tag 'blueberry'. Attachments payload: \(zoneContext.attachments)")
}
blueberryZone.onExit = { zoneContext in
    print("Exited near range of tag 'blueberry'. Attachment payload: \(zoneContext.attachments)")
}

blueberryZone.onContextChange = { contexts in
    print("Now in range of \(contexts.count) contexts")
}

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

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

(Optional) Adding attachments to your beacons

While zone identification is based on tags, attachments are a way to add additional content to a beacon and a zone it defines. Think of it as a custom backend where you can assign any additional data to a particular beacon. All attachments assigned to a beacon will be available in EPXproximityZoneContext objects returned in action's callback. See EPXProximityZone for more details.

To configure 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

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

Assigning beacon attachments

Location and Bluetooth permissions, Background support

Proximity SDK requires Location Services to work in the background, which means you need to ask users to allow the app to access their location. To do that, set up the Location Services usage description:

• Add a value for Privacy - Location Always Usage Description key in your app's Info.plist file. This message will be shown to the user when the app calls ProximityObserver.startObserving(...). It's required for Core Location to work.

Proximity SDK uses Bluetooth, which means you need to ask users to allow the app to access bluetooth. To do that, set up Bluetooth usage description:

• Add a value for Privacy - Bluetooth Always Usage Description key in your app's Info.plist file.

To allow our app to run in the background when in range of beacons, enable the Bluetooth Background Mode:

• Set Uses Bluetooth LE accessories in your Xcode project settings -> Capabilities -> Background Modes. It's required for Core Bluetooth to work in the background.

Additional features

Caching data for projects with limited internet connectivity.

Starting with version 0.13.0, ProximityObserver can store the data necessary for triggering events locally. This allows for performing the typical proximity observation when there is no internet access later on. To enable this, you only need to call ProximityObserver.startObserving([zone1,...]) instance at least once when the internet connection is available - it will then fetch all the necessary data from the Estimote Cloud.

Scanning for Estimote Telemetry

Use case: Getting sensors data from your Estimote beacons.

Starting with version 1.1.0 ProximityObserverConfiguration has exposed properties, one of which allows for reporting telemetry data to Estimote Cloud.

You can easily scan for raw Estimote Telemetry packets that contain your beacons' sensor data. Telemetry is broadcasted in two separate sub-packets, called frame A and frame B. Proximity SDK allows you to scan for the whole merged data at once (containing frame A and B data, and also the full device identifier). Reporting telemetry is enabled by default, but if for any reason you would like to disable this feature, perform the following to stop telemetry reporting:

let proximityConfiguration = ProximityObserverConfiguration.custom(with: .info, requestsCLAuthorization: true, telemetryReportingEnabled: false)

Example apps

To get a working prototype, download a ready-made app template in the Estimote Cloud. App ID & App Token credentials are generated automatically.

• Use Proximity to run a simple demo in the foreground.
• Use Notification to run a demo in the background and display notifications.

Demos require Estimote Beacons configured with Estimote Monitoring

Documentation

Here you will find documentation.

Your feedback and questions

At Estimote we're massive believers in feedback! Here are some common ways to share your thoughts with us:

• Posting issue/question/enhancement on our issues page.
• Asking our community managers on our forum.

Changelog

To see what has changed in recent versions of our SDK, see the CHANGELOG.