{"id":20980527,"url":"https://github.com/hyperjumptech/hypertrace-ios-sdk","last_synced_at":"2025-07-21T07:33:33.979Z","repository":{"id":102269655,"uuid":"445311661","full_name":"hyperjumptech/hypertrace-ios-sdk","owner":"hyperjumptech","description":"OpenTrace iOS SDK","archived":false,"fork":false,"pushed_at":"2022-03-22T08:20:44.000Z","size":157,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-14T15:34:44.921Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperjumptech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2022-01-06T21:10:54.000Z","updated_at":"2024-04-08T14:32:03.000Z","dependencies_parsed_at":"2023-10-29T11:00:25.199Z","dependency_job_id":null,"html_url":"https://github.com/hyperjumptech/hypertrace-ios-sdk","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/hyperjumptech/hypertrace-ios-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjumptech%2Fhypertrace-ios-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjumptech%2Fhypertrace-ios-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjumptech%2Fhypertrace-ios-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjumptech%2Fhypertrace-ios-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperjumptech","download_url":"https://codeload.github.com/hyperjumptech/hypertrace-ios-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjumptech%2Fhypertrace-ios-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266261311,"owners_count":23901289,"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":[],"created_at":"2024-11-19T05:29:02.460Z","updated_at":"2025-07-21T07:33:33.956Z","avatar_url":"https://github.com/hyperjumptech.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperTrace SDK\n\n![HyperTraceSDK](https://github.com/hyperjumptech/hypertrace-ios-sdk/actions/workflows/test.yml/badge.svg)\n\nThis repository contains the iOS SDK for the [BlueTrace protocol](https://bluetrace.io/static/bluetrace_whitepaper-938063656596c104632def383eb33b3c.pdf).\n\n## Installation\n\nUsing Swift Package Manager is the easiest way to install the SDK.\n\n1. Go to Package Dependencies in your Xcode project.\n2. Enter the URL of this repository: https://github.com/hyperjumptech/hypertrace-ios-sdk\n\n## App Requirements\n\nYour app needs to have [Background Modes Capability](https://developer.apple.com/documentation/xcode/configuring-background-execution-modes) enabled for the following modes:\n\n1. Uses Bluetooth LE accessories.\n2. Acts as a Bluetooth LE accessory.\n3. Remote notification.\n\nPlease also add `Privacy - Bluetooth Peripheral Usage Description` and `Privacy - Bluetooth Always Usage Description` in the Info.plist.\n\nYou also need to have a [Hypertrace server](https://github.com/hyperjumptech/hypertrace) running.\n\n## Usage\n\n### Initialization\n\nBefore the tracing started, you need to initialize the SDK and call the `start` function.\n\n```swift\nimport HyperTraceSDK\n\nHyperTrace\n  .shared()\n  .start(baseUrl: \"hypertrace-server-url-here\",\n         uid: UserDefaults.standard.string(forKey: \"userId\")!)\n```\n\n### Setting configuration\n\n#### Interval of the scanning\n\nBy default, the SDK will scan nearby devices every 60 seconds. You can change this value by calling the following function.\n\n```swift\nHyperTrace.setScanningInterval(10) // set the interval every 10 seconds.\n```\n\n#### Duration of the scanning\n\nBy default, the SDK will scan nearby devices for 10 seconds each time. You can change this value by calling the following function.\n\n```swift\nHyperTrace.setScanningDuration(5) // set the duration to 5 seconds.\n```\n\n#### Service ID\n\nTo set the service ID, add a key in Info.plist called `TRACER_SVC_ID`.\n\n#### Characteristic ID\n\nTo set the characteristic ID, add a key in Info.plist called `V2_CHARACTERISTIC_ID`.\n\n#### Organization\n\nTo set the organization ID, add a key in Info.plist called `TRACER_ORG`.\n\n### Data Upload\n\nTo upload the encounters data, call the `upload` function.\n\n```swift\nimport HyperTraceSDK\n\n// code is a security string given by authority\nHyperTrace.shared().upload(code: code) { [weak self] error in\n    guard error == nil else {\n        // show error alert or something\n        return\n    }\n\n    // at this point, you can show success message or something\n}\n```\n\n#### Upload Timeout\n\nUnder the hood, the SDK uses [URLSession](https://developer.apple.com/documentation/foundation/urlsession) with the [default configuration](https://developer.apple.com/documentation/foundation/urlsessionconfiguration), which sets the [request timeout to 60 seconds](https://developer.apple.com/documentation/foundation/urlsessionconfiguration/1408259-timeoutintervalforrequest). To change this value, you need to pass your custom session configuration when calling the `start` function as follows.\n\n```swift\nimport HyperTraceSDK\n\nlet configuration = URLSessionConfiguration.default\nconfiguration.timeoutIntervalForRequest = 1000 // in seconds\n\nHyperTrace\n  .shared()\n  .start(baseUrl: \"hypertrace-server-url-here\",\n         uid: UserDefaults.standard.string(forKey: \"userId\")!,\n         sessionConfiguration: configuration)\n```\n\n### Stop Tracing\n\nTo stop the tracing, call the `stop` function.\n\n```swift\nHyperTrace.shared().stop()\n```\n\n### Data Clean Up\n\nTo prevent excessive amount of encounter data stored in the device, your app needs to call `removeData` function from time to time. It's better to call this function when your app enters foreground.\n\n```swift\nHyperTrace.removeData()\n```\n\nBy default, that function will delete all encounters which are **older** than 21 days. You can change the cut off time as follows\n\n```swift\nHyperTrace.removeData(olderThan: 10, unit: .day) // Remove all encounters which are older than 10 days ago\n```\n\n### Number of Encounters Data\n\nYou can get the number of encounters saved in the device as follows\n\n```swift\nlet encountersCount = HyperTrace.countEncounters() // The default. Get the number of all encounters which are older than 21 days ago\nlet encountersCount2 = HyperTrace.countEncounters(olderThan: 1, unit: .minute) // Get the number of all encounters which are older than 1 minute ago\nlet encountersCount3 = HyperTrace.countEncounters(inTheLast: 1, unit: .minute) // Get the number of all encounters in the last 1 minute\n```\n\n### Debugging\n\nFor debugging purpose, you can observe the encounter logs by getting the [NSFetchedResultsController](https://developer.apple.com/documentation/coredata/nsfetchedresultscontroller) instance.\n\n```swift\nimport HyperTraceSDK\nimport CoreData\n\nclass LogViewController: UITableViewController {\n  var fetchedResultsController: NSFetchedResultsController\u003cEncounter\u003e?\n\n\n  override func viewDidLoad() {\n    super.viewDidLoad()\n\n    self.navigationItem.rightBarButtonItem = UIBarButtonItem(title: \"Upload\", style: .plain, target: self, action: #selector(addTapped))\n\n    // get the NSFetchedResultsController instance from HyperTrace SDK\n    fetchedResultsController = HyperTrace.shared().getFetchedResultsController(delegate: self)\n  }\n\n\n  override func viewWillAppear(_ animated: Bool) {\n    do {\n      // start fetching and listening to the encounters\n      try fetchedResultsController?.performFetch()\n    } catch let error as NSError {\n      print(\"Could not perform fetch. \\(error), \\(error.userInfo)\")\n    }\n  }\n}\n```\n\nFor a working example, see the [HyperTrace Sample app](https://github.com/hyperjumptech/hypertrace-ios-sdk-sample).\n\n## Linting\n\nThis project uses [SwiftFormat](https://github.com/nicklockwood/SwiftFormat) to format and lint the swift files. The GitHub Actions workflow will lint the swift files before running the tests. To lint the swift files locally, run the following command.\n\n```shell\nswiftformat --lint Sources\n```\n\nTo format your swift files, run the following command.\n\n```shell\nswiftformat Sources\n```\n\n## Testing\n\nThe tests can be run either from the Xcode, or from the Terminal using the following command\n\n```shell\n# Run the tests and generate coverage\nxcodebuild -scheme HyperTraceSDK -enableCodeCoverage YES -derivedDataPath build/ clean build test -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 12 Pro'\n# Show the compact coverage result in the terminal\nxcrun xccov view --report --only-targets ./build/Logs/Test/*.xcresult\n```\n\n## License\n\nGNU General Public License v3.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperjumptech%2Fhypertrace-ios-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperjumptech%2Fhypertrace-ios-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperjumptech%2Fhypertrace-ios-sdk/lists"}