{"id":22756498,"url":"https://github.com/sagarsdagdu/sdbeaconscanner","last_synced_at":"2025-07-21T06:32:23.917Z","repository":{"id":253826630,"uuid":"843688609","full_name":"SagarSDagdu/SDBeaconScanner","owner":"SagarSDagdu","description":"SDBeaconScanner is a Swift library for scanning Bluetooth beacons using CoreLocation's beacon ranging API. It simplifies scanning for beacons by providing an easy-to-use API with support for UUID, major, and minor identifiers. ","archived":false,"fork":false,"pushed_at":"2025-05-28T12:22:11.000Z","size":55,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-28T13:28:25.179Z","etag":null,"topics":["beacon-scanner","beacons","clbeacon","corelocation","ios-beacons"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SagarSDagdu.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2024-08-17T05:43:46.000Z","updated_at":"2025-05-28T12:21:37.000Z","dependencies_parsed_at":"2025-07-21T06:31:59.959Z","dependency_job_id":null,"html_url":"https://github.com/SagarSDagdu/SDBeaconScanner","commit_stats":null,"previous_names":["sagarsdagdu/sdbeaconscanner"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/SagarSDagdu/SDBeaconScanner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SagarSDagdu%2FSDBeaconScanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SagarSDagdu%2FSDBeaconScanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SagarSDagdu%2FSDBeaconScanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SagarSDagdu%2FSDBeaconScanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SagarSDagdu","download_url":"https://codeload.github.com/SagarSDagdu/SDBeaconScanner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SagarSDagdu%2FSDBeaconScanner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266253614,"owners_count":23900053,"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":["beacon-scanner","beacons","clbeacon","corelocation","ios-beacons"],"created_at":"2024-12-11T07:14:00.559Z","updated_at":"2025-07-21T06:32:23.896Z","avatar_url":"https://github.com/SagarSDagdu.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛰️ SDBeaconScanner\n\n\nSDBeaconScanner is a Swift library for scanning Bluetooth beacons using CoreLocation's beacon ranging API. It simplifies scanning for beacons by providing an easy-to-use API with support for UUID, major, and minor identifiers. Additionally, the scanner allows you to specify a timeout for the scan and handles beacon detection results through completion handlers.\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n    - [Swift Package Manager](#swift-package-manager)\n    - [Manually](#manually)\n- [Permissions](#permissions)\n- [Project Configuration](#project-configuration)\n- [Usage](#usage)\n    - [Importing the Library](#1-importing-the-library)\n    - [Initializing the Scanner](#2-initializing-the-scanner)\n    - [Scanning for Beacons](#3-scanning-for-beacons)\n    - [Customizing the Timeout](#4-customizing-the-timeout)\n    - [Handling Results and Errors](#5-handling-results-and-errors)\n- [Example](#example)\n- [License](#license)\n\n## Features\n\n- **Beacon Scanning:** Scan for nearby Bluetooth beacons by UUID, with optional major and minor values.\n- **Customizable Timeout:** Specify a custom timeout for the scan to avoid indefinite scanning.\n- **Completion Handlers:** Results are returned via completion handlers, making it easy to integrate with your existing app logic.\n- **Error Handling:** Provides detailed errors, including invalid UUID, unavailable ranging, and generic errors via NSError.\n\n## Requirements\n\n- iOS 13.0+\n- Swift 5.0+\n- `CoreLocation` framework\n\n## Installation\n\n### Swift Package Manager\n\nAdd SDBeaconScanner to your project using Swift Package Manager:\n\n1. Open your Xcode project.\n2. Select **File** \u003e **Add Packages**.\n3. Paste the repository URL in the search field:\n```\nhttps://github.com/SagarSDagdu/SDBeaconScanner.git\n```\n4. Choose the package and add it to your project.\n\n### Manually\n\nYou can manually copy the files under `Sources/SDBeaconScanner` to your project.\n\n## Permissions\nEnsure that your app includes the necessary permissions in `Info.plist` to use location services:\n\n```xml\n\u003ckey\u003eNSLocationWhenInUseUsageDescription\u003c/key\u003e\n\u003cstring\u003eWe need your location to scan for beacons.\u003c/string\u003e\n\u003ckey\u003eNSLocationAlwaysUsageDescription\u003c/key\u003e\n\u003cstring\u003eWe need your location to scan for beacons even when the app is in the background.\u003c/string\u003e\n\u003ckey\u003eNSLocationAlwaysAndWhenInUseUsageDescription\u003c/key\u003e\n\u003cstring\u003eWe need your location to scan for beacons.\u003c/string\u003e\n```\n\n## Project Configuration\n\n### Background Location Updates\nTo enable scanning for beacons while your app is in the background, ensure that your app has the correct background modes enabled in Info.plist:\n\n```xml\n\u003ckey\u003eUIBackgroundModes\u003c/key\u003e\n\u003carray\u003e\n    \u003cstring\u003elocation\u003c/string\u003e\n\u003c/array\u003e\n```\n\n## Usage\n\n### 1. Importing the Library\n\n```swift\nimport SDBeaconScanner\n```\n\n### 2. Initializing the Scanner\n\nSDBeaconScanner is designed as a singleton, so you can directly access the shared instance:\n\n```swift\nlet beaconScanner = SDBeaconScanner.shared\n```\n\n### 3. Scanning for Beacons\n\nTo start scanning for beacons, you can use either of the following methods depending on whether you want to scan by UUID only or include major and minor values.\n\n#### Scan by UUID\n\n```swift\nbeaconScanner.getNearbyBeacons(uuid: \"your-uuid\") { scanResult in\n     switch scanResult {\n        case let .success(beacons):\n             print(\"Got \\(beacons.count) beacons\")\n        case let .failure(scanError):\n             print(\"Error: \\(scanError)\")\n    }\n}\n```\n\n#### Scan by UUID, Major, and Minor\n\n```swift\nbeaconScanner.getNearbyBeacons(uuid: \"your-uuid\", major: 123, minor: 456) { scanResult in\n     switch scanResult {\n        case let .success(beacons):\n             print(\"Got \\(beacons.count) beacons\")\n        case let .failure(scanError):\n             print(\"Error: \\(scanError)\")\n    }\n}\n```\n\n### 4. Customizing the Timeout\n\nYou can specify a custom timeout duration (in seconds) for the scan. The scan will automatically stop once the timeout is reached or once beacons are found.\n\n```swift\nbeaconScanner.getNearbyBeacons(uuid: \"your-uuid\", timeout: 10.0) { scanResult in\n    switch scanResult {\n        case let .success(beacons):\n             print(\"Got \\(beacons.count) beacons\")\n        case let .failure(scanError):\n             print(\"Error: \\(scanError)\")\n    }\n}\n```\n\n### 5. Handling Results and Errors\n\nThe `BeaconScanningCompletion` typealias is used for handling the results of a scan. You can check for errors and handle the returned beacons in the completion handler.\n\n### Error Handling\n\nSDBeaconScanner provides detailed error handling through the `BeaconScannerError` enum. The following errors are reported:\n\n- `invalidUUID`: Indicates that the provided UUID is not valid.\n- `rangingUnavailable`: Indicates that the device does not support ranging.\n- `rangingFailed(NSError)`: A generic error that reports an `NSError` object, typically triggered by internal location manager issues.\n\nExample usage:\n\n```swift\n    switch error {\n    case .invalidUUID:\n        print(\"The UUID provided is invalid.\")\n    case .rangingUnavailable:\n        print(\"Ranging is unavailable on this device.\")\n    case .rangingFailed(let nsError):\n        print(\"Ranging failed with error: \\(nsError.localizedDescription)\")\n    }\n```\n\n## Example\n\nYou can find a simple example project in the [Example](/Example) directory. The example demonstrates how to scan for beacons using `SDBeaconScanner`.\n\n## License\n\nSDBeaconScanner is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsagarsdagdu%2Fsdbeaconscanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsagarsdagdu%2Fsdbeaconscanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsagarsdagdu%2Fsdbeaconscanner/lists"}