{"id":18575773,"url":"https://github.com/estimote/ios-proximity-sdk","last_synced_at":"2025-08-08T18:35:25.189Z","repository":{"id":56910077,"uuid":"114749554","full_name":"Estimote/iOS-Proximity-SDK","owner":"Estimote","description":"Estimote Proximity SDK for iOS","archived":false,"fork":false,"pushed_at":"2023-09-25T15:38:27.000Z","size":88075,"stargazers_count":62,"open_issues_count":19,"forks_count":26,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-04-17T00:54:05.976Z","etag":null,"topics":["beacons","estimote","ios","proximity"],"latest_commit_sha":null,"homepage":"https://developer.estimote.com","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Estimote.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-19T10:07:18.000Z","updated_at":"2024-06-18T21:22:21.524Z","dependencies_parsed_at":"2023-02-14T08:16:49.733Z","dependency_job_id":"8a2198c4-3b6f-4b2f-8a91-f161df983991","html_url":"https://github.com/Estimote/iOS-Proximity-SDK","commit_stats":{"total_commits":66,"total_committers":13,"mean_commits":5.076923076923077,"dds":0.696969696969697,"last_synced_commit":"91ef4dccfa402524896b80f3f930e85fc70cb0ec"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Estimote%2FiOS-Proximity-SDK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Estimote%2FiOS-Proximity-SDK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Estimote%2FiOS-Proximity-SDK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Estimote%2FiOS-Proximity-SDK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Estimote","download_url":"https://codeload.github.com/Estimote/iOS-Proximity-SDK/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248185268,"owners_count":21061485,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beacons","estimote","ios","proximity"],"created_at":"2024-11-06T23:22:02.941Z","updated_at":"2025-04-10T08:30:54.585Z","avatar_url":"https://github.com/Estimote.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Estimote Proximity SDK - iOS\nStick 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.\n\n**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][reliability-numbers])\n\n[reliability-numbers]: http://blog.estimote.com/post/165007958785/launching-the-most-reliable-configurationless#better-reliability\n\nOther Proximity SDK highlights include:\n\n1. **Tag-based identification:** define your proximity zones with human-readable tags instead of abstract identifiers.\n2. **Multiple zones per beacon:** set up more than one enter/exit zone per single beacon. (e.g., a “near” zone and a “far” zone)\n3. **Software-defined range:** define the enter/exit trigger range in code, rather than by the beacon’s broadcasting power.\n4. **Cloud-based tagging \u0026 grouping:** add, remove, and replace beacons, without changing the app’s code - just modify the tags in Estimote Cloud.\n\n# Table of contents\n- [Tag-based identification](#tag-based-identification)\n- [Installation](#installation)\n- [Use it in your app](#use-it-in-your-app)\n    - [Setting up tags](#setting-up-tags)\n    - [Inside your app](#inside-your-app)\n- [(Optional) Adding attachments to your beacons](#optional-adding-attachments-to-your-beacons)\n- [Location and Bluetooth permissions, Background support](#location-and-bluetooth-permissions-background-support)\n- [Additional features](#additional-features)\n- [Example apps](#example-apps)\n- [Documentation](#documentation)\n- [Your feedback and questions](#your-feedback-and-questions)\n- [Changelog](#changelog)\n\n## Tag-based identification\nEstimote Proximity SDK uses tag-based identification to allow for dynamic setup changes.\nYou monitor beacons by tags, which you assign in Estimote Cloud. For example, instead of saying:\n\u003e\"monitor for beacon 123 and beacon 456\"\n\nyou say: \n\n\u003e\"monitor for beacons tagged as lobby\". \n\nThis 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.\n\u003e**Important!**\n\u003eAs 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. \n\n### Key components\nEstimote 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.\n- _Observer_ - responsible for starting and stopping monitoring for a provided list of zones,\n- _Zone_ - a representation for a physical space combining group of beacons with same _tag_.\n- _Zone’s context_ - a combination of a single beacon with its tag and list of attachments assigned to it.\n- _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.\n\nBelow there's a presentation of two zones:\n- `blueberry` zone with two _zone's contexts_,\n- `mint`zone with only one _zone's context_.\n\n![](readme_images/tag_based_sdk.png)\n\n\u003cp align=\"center\"\u003e\n    \u003ci\u003eTag-based zones\u003c/i\u003e\n\u003c/p\u003e\n\n## Installation\n\n### Swift compatibility\n\nStarting with [version 1.2.0](https://github.com/Estimote/iOS-Proximity-SDK/releases/tag/v1.2.0) Proximity SDK supports Swift 4.2.\n\n### Swift Package Manager \n\nFollow the article about [Adding Package Dependencies to Your App](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app) using the following repository URL: `https://github.com/Estimote/iOS-Proximity-SDK`.\n\n### CocoaPods \n[CocoaPods](https://cocoapods.org/) is an easy way to add external libraries. To use it to fetch Proximity SDK:\n1. Add `pod 'EstimoteProximitySDK'` to your Podfile\n1. Run `pod install --repo-update`\n1. 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.\n1. Add `import EstimoteProximitySDK` (Swift) or  `#import \u003cEstimoteProximitySDK/EstimoteProximitySDK.h\u003e` (Objective–C) to your code\n\n### Manual\n1. Download Proximity SDK repository\n    - Click the _Download ZIP_ button in this repo, or\n    - Run `git clone git@github.com:Estimote/iOS-SDK-Proximity-SDK.git --depth=1`\n1. Download Bluetooth Scanning library repo\n    - Click the _Download ZIP_ button in [Bluetooth Scanning repo](https://github.com/Estimote/iOS-Bluetooth-Scanning), or\n    - Run `git clone git@github.com:Estimote/iOS-Bluetooth-Scanning.git --depth=1`\n1. Drag \u0026 drop [EstimoteProximitySDK.framework](EstimoteProximitySDK/EstimoteProximitySDK.framework) to your project (enable the checkbox in _Options_ \u003e _Copy files if needed_)\n1. Drag \u0026 drop [EstimoteBluetoothScanning.framework](EstimoteProximitySDK/EstimoteBluetoothScanning.framework) to your project (enable the checkbox in _Options_ \u003e _Copy files if needed_)\n1. Add Estimote Proximity SDK to your Xcode project's _Build Phases_ \u003e _Embed Frameworks_. If this build phase isn't visible you can add the SDK in _General_ -\u003e _Embedded Binaries_ section.\n1. Add Estimote Bluetooth Scanning library to your Xcode project's _Build Phases_ \u003e _Embed Frameworks_. If this build phase isn't visible you can add the SDK in _General_ -\u003e _Embedded Binaries_ section.\n1. 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.\n1. Add `import EstimoteProximitySDK` (Swift) or  `#import \u003cEstimoteProximitySDK/EstimoteProximitySDK.h\u003e` (Objective–C) to your code\n\n## Use it in your app\nThe 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.\n### Requirements\n- One or more [Estimote Proximity Beacons](https://estimote.com/products/) with Estimote Monitoring enabled. Here’s [how to enable it.](https://community.estimote.com/hc/en-us/articles/226144728-How-to-enable-Estimote-Monitoring) \n- An iOS device with Bluetooth Low Energy running iOS 10 or later. Using BLE with iOS Simulator isn't supported.\n- An Estimote Cloud account.\n\n### Setting up tags\nTo configure the tags:\n1. Go to https://cloud.estimote.com/#/\n1. Click on the beacon you want to configure\n1. Click _Edit Settings_ button\n1. Click _Tags_ field and a drop down list with (if applicable) existing tags.\n1. 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).\n1. Click _Save Changes_\n\n\u003eTags are Cloud-only settings — no additional connecting to the beacons with the Estimote app is required!\n\n![](readme_images/assign_tag.png)\n\n\u003cp align=\"center\"\u003e\n    \u003ci\u003eAssigning beacon tags\u003c/i\u003e\n\u003c/p\u003e\n\n### Inside your app\nTo use the SDK within your app, go to the [apps section](https://cloud.estimote.com/#/apps) in Estimote Cloud. Register a new app or use one of the available templates to obtain App ID \u0026 App Token credentials pair.\nIn your app, set up the credentials using `CloudCredentials`:\n```swift\nlet credentials = CloudCredentials(appID: \"your-app-id\", appToken: \"your-app-token\")\n```\nThen, configure proximity discovery with `ProximityObserver`. For more info on tags, see [this section](#tag-based-identification) or [documentation](#documentation).\n```swift\n// Create observer instance\nself.proximityObserver = ProximityObserver(credentials: credentials, onError: { error in\n    print(\"Oops! \\(error)\")\n})\n// Define zones\nlet blueberryZone = ProximityZone(tag: \"blueberry\", range: ProximityRange.near)\nblueberryZone.onEnter = { zoneContext in\n    print(\"Entered near range of tag 'blueberry'. Attachments payload: \\(zoneContext.attachments)\")\n}\nblueberryZone.onExit = { zoneContext in\n    print(\"Exited near range of tag 'blueberry'. Attachment payload: \\(zoneContext.attachments)\")\n}\n\nblueberryZone.onContextChange = { contexts in\n    print(\"Now in range of \\(contexts.count) contexts\")\n}\n\n// ... etc. You can define as many zones as you need.\n\n// Start proximity observation\nself.proximityObserver.startObserving([blueberryZone])\n```\n\n\n### (Optional) Adding attachments to your beacons\nWhile 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.\nAll attachments assigned to a beacon will be available in `EPXproximityZoneContext` objects returned in action's callback. See [EPXProximityZone](https://github.com/Estimote/iOS-Proximity-SDK-Source/blob/feature/tags_readme/EstimoteProximitySDK/EstimoteProximitySDK/PublicClasses/EPXProximityRange.h) for more details.\n\nTo configure the attachments:\n1. Go to https://cloud.estimote.com/#/\n1. Click on the beacon you want to configure\n1. Click _Settings_ button\n1. Click _Beacon Attachment_ field\n1. Add any attachment key-value pair you want\n1. Click _Save Changes_\n\n\u003eAttachments are Cloud-only settings — no additional connecting to the beacons with the Estimote app is required!\n\n![](readme_images/adding_attachments.png)\n\n\u003cp align=\"center\"\u003e\n\u003ci\u003eAssigning beacon attachments\u003c/i\u003e\n\u003c/p\u003e\n\n## Location and Bluetooth permissions, Background support\n\nProximity 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**:\n\n- 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.\n\nProximity 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**:\n\n- Add a value for _Privacy - Bluetooth Always Usage Description_ key in your app's Info.plist file.\n\nTo allow our app to run in the background when in range of beacons, **enable the Bluetooth Background Mode**:\n\n- Set _Uses Bluetooth LE accessories_ in your Xcode project settings -\u003e _Capabilities_ -\u003e _Background Modes_. It's ***required*** for Core Bluetooth to work in the background.\n## Additional features\n\n### Caching data for projects with limited internet connectivity.\nStarting with version [0.13.0](https://github.com/Estimote/iOS-Proximity-SDK/releases/tag/v0.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.\n\n### Scanning for Estimote Telemetry\n\n\u003eUse case: Getting sensors data from your Estimote beacons.\n\nStarting with version [1.1.0](https://github.com/Estimote/iOS-Proximity-SDK/releases/tag/v1.1.0) `ProximityObserverConfiguration` has exposed properties, one of which allows for reporting telemetry data to Estimote Cloud.\n\nYou 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:\n\n```swift\nlet proximityConfiguration = ProximityObserverConfiguration.custom(with: .info, requestsCLAuthorization: true, telemetryReportingEnabled: false)\n```\n\n## Example apps\n\nTo get a working prototype, download a [ready-made app template](https://cloud.estimote.com/#/apps/add) in the Estimote Cloud. \nApp ID \u0026 App Token credentials are generated automatically.\n\n- Use [Proximity](https://cloud.estimote.com/#/apps/add/proximity-content-multiple) to run a simple demo in the foreground.\n- Use [Notification](https://cloud.estimote.com/#/apps/add/notification) to run a demo in the background and display notifications.\n\nDemos require Estimote Beacons [configured with Estimote Monitoring](https://community.estimote.com/hc/en-us/articles/226144728-How-to-enable-Estimote-Monitoring)\n\n## Documentation\n[Here](https://estimote.github.io/iOS-Proximity-SDK) you will find documentation.\n\n## Your feedback and questions\nAt Estimote we're massive believers in feedback! Here are some common ways to share your thoughts with us:\n- Posting issue/question/enhancement on our [issues page](https://github.com/Estimote/iOS-Proximity-SDK/issues).\n- Asking our community managers on our [forum](https://forums.estimote.com/c/proximity).\n\n## Changelog\nTo see what has changed in recent versions of our SDK, see the [CHANGELOG](https://github.com/Estimote/iOS-Proximity-SDK/blob/master/CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Festimote%2Fios-proximity-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Festimote%2Fios-proximity-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Festimote%2Fios-proximity-sdk/lists"}