search

Estimote / iOS-Proximity-SDK

Estimote Proximity SDK for iOS
https://developer.estimote.com
Apache License 2.0
62 stars 27 forks source link
beacons estimote ios proximity

readme

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

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.

Below there's a presentation of two zones:

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 git@github.com: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 git@github.com: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

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:

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:

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

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.

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:

Changelog

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