{"id":19870901,"url":"https://github.com/beaconstac/ios-sdk","last_synced_at":"2025-05-02T08:32:43.471Z","repository":{"id":27436449,"uuid":"30914446","full_name":"Beaconstac/iOS-SDK","owner":"Beaconstac","description":"Beaconstac ADVANCED SDK for iOS devices","archived":false,"fork":false,"pushed_at":"2023-01-31T07:16:53.000Z","size":102540,"stargazers_count":21,"open_issues_count":2,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-03-24T16:20:27.901Z","etag":null,"topics":["beacon","ibeacon","ios-sdk","proximity-advertising","proximity-marketing","swift-sdk","swift4"],"latest_commit_sha":null,"homepage":"https://dashboard.beaconstac.com","language":"Objective-C","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/Beaconstac.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}},"created_at":"2015-02-17T11:37:15.000Z","updated_at":"2023-08-17T07:36:03.000Z","dependencies_parsed_at":"2023-02-16T17:00:55.803Z","dependency_job_id":null,"html_url":"https://github.com/Beaconstac/iOS-SDK","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FiOS-SDK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FiOS-SDK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FiOS-SDK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FiOS-SDK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Beaconstac","download_url":"https://codeload.github.com/Beaconstac/iOS-SDK/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252008951,"owners_count":21679669,"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","ibeacon","ios-sdk","proximity-advertising","proximity-marketing","swift-sdk","swift4"],"created_at":"2024-11-12T16:10:34.347Z","updated_at":"2025-05-02T08:32:42.770Z","avatar_url":"https://github.com/Beaconstac.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iOS-SDK\n\n## Introduction\n\nBeaconstac Advanced iOS SDK is meant only for specialized use cases. Please check with the support team before deciding to integrate this SDK.\n\n## Documentation\n\n* Please refer to the [API reference](http://cocoadocs.org/docsets/Beaconstac).\n\n## Demo app\n\nTry out the Beaconstac Demo app on the [iTunes App Store](https://itunes.apple.com/us/app/beaconstac/id956442796?mt=8).\n\n## Installation\n##### Using Cocoapods (recommended):\nAdd the following to your Podfile in your project, we are supporting iOS 10.0+ make sure your pod has proper platform set.\n\n```pod\nplatform :ios, '10.0'\ntarget '\u003cMy-App-Target\u003e''\n  pod 'Beaconstac', '~\u003e 3.2.9'\nend\n```\n\nRun `pod install` in the project directory\n\n\n#### Manually:\n\n1. Download or clone this repo on your system.\n2. Drag and drop the Beaconstac.framework file into your Xcode project. Make sure that \"Copy Items to Destination's Group Folder\" is checked.\n\u003cimg src=\"images/frameworkdrop.png\" alt=\"Build Phases\" width=\"600\"\u003e\n\n3. Add the `Beaconstac.framework` and `EddystoneScanner.framework` to the embedded binaries section of your destination app target.\n\n4. In Build Phases under destination app target, add the following frameworks in Link Binary With Libraries section:\n- CoreData.framework\n- SystemConfiguration.framework\n- CoreBluetooth.framework\n- CoreLocation.framework\n- EddystoneScanner.framework\n\n## Configure your project\n\n1. In Info.plist, add a new fields, `NSLocationAlwaysUsageDescription`, `NSLocationAlwaysAndWhenInUsageDescription`, `NSBluetoothPeripheralUsageDescription` with relevant values that you want to show to the user. This is mandatory for iOS 10 and above.\n\u003cimg src=\"images/usagedescription.png\" alt=\"Build Phases\" width=\"600\"\u003e\n\n## Pre-requisites\n\n### Location\n\nThe app should take care of handling permissions as required.\n\n1. To receive notifications in the background you must first enable the `Location Updates` and `Uses Bluetooth LE accessories` Background Modes in the Capabilities tab of your app target.\n\n\n\n```swift\nvar locationManager = CLLocationManager()\nlocationManager.delegate = self\nlocationManager.requestAlwaysAuthorization()\n\nfunc locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {\n    if status == .authorizedAlways {\n        if beaconstac != nil {\n            beaconstac?.startScanningBeacons()\n        } else {\n            // Initialise Beaconstac SDK\n        }\n    } else {\n        beaconstac?.stopScanningBeacons()\n\n        // Show Alert to enable alwyas permission\n    }\n}\n\n// Make sure you retain the CLLocationManager for the callbacks\n// You need to handle the case where user doesn't provide `Always` permission\n```\n\n```objective-c\nCLLocationManager *locationmanager = [[CLLocationManager alloc] init];\nlocationManager.delegate = self;\n[locationManager requestAlwaysAuthorization];\n\n- (void)locationManager:(CLLocationManager *)manager \ndidChangeAuthorizationStatus:(CLAuthorizationStatus)status {\n    if (status == kCLAuthorizationStatusAuthorizedAlways) {\n        if beaconstac != nil {\n           [beaconstac startScanningBeacons];\n        } else {\n            // Initialise Beaconstac SDK\n        }\n    } else {\n        [beaconstac stopScanningBeacons];\n\n        // Show Alert to enable always permission\n    }\n}\n// Make sure you retain the CLLocationManager for the callbacks\n// You need to handle the case where user doesn't provide `Always` permission\n```\n\n2. To receive notifications only in the foreground\n\n```swift\nvar locationManager = CLLocationManager()\nlocationManager.delegate = self\nlocationManager.requestWhenInUseAuthorization()\n\nfunc locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {\n    if status == authorizedWhenInUse || status == .authorizedAlways {\n        if beaconstac != nil {\n            beaconstac?.startScanningBeacons()\n        } else {\n            // Initialise Beaconstac SDK\n        }\n    } else {\n        beaconstac?.stopScanningBeacons()\n\n        // Show Alert to enable permission\n    }\n}\n\n// Make sure you retain the CLLocationManager for the callbacks\n// You need to handle the case where user doesn't provide permission\n```\n\n```objective-c\nCLLocationManager *locationmanager = [[CLLocationManager alloc] init];\nlocationManager.delegate = self;\n[locationManager requestWhenInUseAuthorization];\n\n- (void)locationManager:(CLLocationManager *)manager \ndidChangeAuthorizationStatus:(CLAuthorizationStatus)status {\n    if (status == kCLAuthorizationStatusAuthorizedWhenInUse || status == kCLAuthorizationStatusAuthorizedAlways) {\n        if beaconstac != nil {\n           [beaconstac startScanningBeacons];\n        } else {\n            // Initialise Beaconstac SDK\n        }\n    } else {\n        [beaconstac stopScanningBeacons];\n\n        // Show Alert to enable alwyas permission\n    }\n}\n// Make sure you retain the CLLocationManager for the callbacks\n// You need to handle the case where user doesn't provide permission\n```\n\n\n__Bluetooth__\n\nThe app should take care of enabling the bluetooth to range beacons.\n\n```swift\nvar bluetoothManager = CBCentralManager(delegate: self, queue: nil, options: nil)\n\nfunc centralManagerDidUpdateState(_ central: CBCentralManager) {\n    if central.state == .poweredOn {\n        beaconstac?.startScanningBeacons()\n    } else {\n        beaconstac?.stopScanningBeacons()\n    }\n}\n\n// Make sure you retain the CBCentralManager for the callbacks\n// You need to handle the case where user doesn't provide permission\n```\n\n```objective-c\nCBCentralManager *bluetoothManager = [[CBCentralManager alloc] initWithDelegate:self queue:nil options:nil];\n\n- (void)centralManagerDidUpdateState:(CBCentralManager *)central {\n    if (central.state == CBManagerStatePoweredOn) {\n        [beaconstac startScanningBeacons];\n    } else {\n        [beaconstac stopScanningBeacons];\n    }\n}\n// Make sure you retain the CBCentralManager for the callbacks\n// You need to handle the case where user doesn't provide permission\n```\n\n__MY_DEVELOPER_TOKEN__\n\nThe app should provide the developer token while initializing the SDK. Get it from [Beaconstac Dashboard Account Page](https://dashboard.beaconstac.com/#/account).\n\n__Monitoring Regions__\n\nIf you are using the region monitoring API's from advanced location manager, make sure it won't affect the Beaconstac SDK.\n\n## Set Up\n\n1. Import the framework header in your class\n\n```swift\nimport Beaconstac\n```\n\n```objective-c\nimport \u003cBeaconstac/Beaconstac.h\u003e\n```\n\n2. Initialize `Beaconstac` using __one-line initialization__, the initialization starts scanning for beacons immediately.\n\n```swift\ndo {\n    Beaconstac.sharedInstance(\"MY_DEVELOPER_TOKEN\", completion: : { (beaconstac, error) in\n      if let beaconstacInstance = beaconstac {\n        // Successful...\n      } else if let e = error {\n        print(e)\n      }\n    }))\n} catch let error {\n    print(error)\n}\n```\n\n```objective-c\n[Beaconstac sharedInstance:\"\" ibeaconOption:iBeaconOptionWhenInUseRange organization:123 delegate:self completion:^(Beaconstac * _Nullable beaconstacInstance, NSError * _Nullable error){\n    if (!error) {\n        //Successfull\n    } else {\n        NSLog(\"%@\", error);\n    }\n}];\n```\n\n\n3. If you want to use the `advacnced integration`, use __iBeaconOption__ as defined below\n\n| iBeaconOption                  |    Location Authorization  | Monitoring                       | Ranging                   | Description                                       |\n|:------------------------------:|:--------------------------:|:--------------------------------:| :------------------------:|:----------------------------------------------:|\n|              WhenInUse         |  When In Use Authorization | CoreLocation API doesn't support | CoreLocation API supports | SDK works only in the foreground               |\n| BackgroundRangeOnDisplayWakeUp |  Always Authorization      | CoreLocation API supports        | CoreLocation API supports | SDK works in the background as well            |\n\n```swift\ndo {\n    Beaconstac.sharedInstance(\"My_DEVELOPER_TOKEN\", ibeaconOption: .BackgroundRangeOnDisplayWakeUp, delegate: self, completion: : { (beaconstac, error) in\n      if let beaconstacInstance = beaconstac {\n          beaconstac?.startScanningBeacons()\n          // Initialization successful, it just works...\n      } else if let e = error {\n          print(e)\n      }\n    })\n} catch let error {\n    print(error)\n}\n```\n\n```objective-c\n[Beaconstac sharedInstance:\"\" ibeaconOption:iBeaconOptionWhenInUseRange organization:123 delegate:self completion:^(Beaconstac * _Nullable beaconstacInstance, NSError * _Nullable error){\n    if (!error) {\n        //Successfull\n      [beaconstacInstance startScanningBeacons]; \n    } else {\n        NSLog(\"%@\", error);\n    }\n}];\n```\n\n4. If you wish to get the ___sharedInstance()___ of the Beaconstac SDK, after you initialize the Beaconstac SDK at any point in a single application life cycle\n\n```swift\ndo {\n    beaconstacInstance = try Beaconstac.sharedInstance()\n} catch let error {\n    print(error)\n}\n```\n\n```objective-c\nNSError *error = nil;\n[Beaconstac sharedInstanceAndReturnError:\u0026error];\n```\n\n5. If you wish to control start and stop of scanning for beacons:\n\n```swift\nbeaconstac.startScanningBeacons() // Starts scanning for beacons...\nbeaconstac.stopScanningBeacons() // Stops scanning for beacons...\n```\n\n```objective-c\n[beaconstacInstance startScanningBeacons];\n[beaconstacInstance stopScanningBeacons];\n```\n\n6. Implement `BeaconDelegate` protocol methods to receive callbacks when beacons are scanned\n\n```swift\n\n// In the class where you want to listen to the beacon scanning events...\nbeaconstacInstance = try! Beaconstac.sharedInstance()\nbeaconstacInstance.delegate = self\n\n// required\nfunc didFail(_ beaconstac: Beaconstac, error: Error) {\n    print(error)\n}\n\n//Optional\nfunc didEnterRegion(_ beaconstac: Beaconstac, region: String) {\n    print(region)\n}\n\nfunc didRangeBeacons(_ beaconstac: Beaconstac, beacons: [MBeacon]) {\n    print(beacons)\n}\n\nfunc didEnterBeacon(_ beaconstac: Beaconstac, beacon: MBeacon) {\n    print(beacon)\n}\n\nfunc didExitBeacon(_ beaconstac: Beaconstac, beacon: MBeacon) {\n    print(beacon)\n}\n\nfunc didExitRegion(_ beaconstac: Beaconstac, region: String) {\n    print(region)\n}\n```\n\n```objective-c\n\n// In the class where you want to listen to the beacon scanning events...\nNSError *error = nil;\nBeconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:\u0026error];\nbeaconstacInstance.delegate = self;\n\n// required\n- (void)didFail:(Beaconstac * _Nonnull)beaconstac error:(NSError * _Nonnull)error {\n    NSLog(\"%@\", error);\n}\n\n//Optional\n- (void)didEnterRegion:(Beaconstac * _Nonnull)beaconstac region:(NSString * _Nonnull)region {\n    NSLog(\"%@\", region);\n}\n    \n- (void)didRangeBeacons:(Beaconstac * _Nonnull)beaconstac beacons:(NSArray\u003cMBeacon *\u003e * _Nonnull)beacons {\n    NSLog(\"%@\", beacons);\n}\n    \n- (void)campOnBeacon:(Beaconstac * _Nonnull)beaconstac beacon:(MBeacon * _Nonnull)beacon {\n    NSLog(\"%@\", beacon);\n}\n    \n- (void)exitBeacon:(Beaconstac *)beaconstac beacon:(MBeacon *)beacon {\n    NSLog(\"%@\", beacon);\n}\n    \n- (void)didExitRegion:(Beaconstac * _Nonnull)beaconstac region:(NSString * _Nonnull)region {\n    NSLog(\"%@\", region);\n}\n```\n\n7. Implement `RuleProcessorDelegate` protocol methods to receive callbacks when rules are triggered\n\n```swift\n\n// In the class where you want to listen to the rule triggering events...\nbeaconstacInstance = try! Beaconstac.sharedInstance()\nbeaconstacInstance.ruleDelegate = self\n\nfunc willTriggerRule(_ beaconstac: Beaconstac, rule: MRule) {\n    // read which rule is about to trigger and the actions, filters set by the marketers...\n}\n\nfunc didTriggerRule(_ beaconstac: Beaconstac, rule: MRule) {\n    // read which rule is triggered and the actions, filters set by the marketers...\n}\n```\n\n```objective-c\n\n// In the class where you want to listen to the rule triggering events...\nNSError *error = nil;\nBeconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:\u0026error];\nbeaconstacInstance.ruleDelegate = self;\n\n- (void)willTriggerRule:(Beaconstac * _Nonnull)beaconstac rule:(MRule * _Nonnull)rule {\n    // read which rule is about to trigger and the actions, filters set by the marketers...\n}\n\n- (void)didTriggerRule:(Beaconstac * _Nonnull)beaconstac rule:(MRule * _Nonnull)rule {\n    // read which rule is triggered and the actions, filters set by the marketers...\n}\n```\n\n8. Implement `NotificationDelegate` protocol methods to override the display of the Local Notification.\n\n```swift\n\n// In the class where you want to listen to notification events...\nbeaconstacInstance = try! Beaconstac.sharedInstance()\nbeaconstacInstance.notificationDelegate = self\n\nfunc overrideNotification(_ beaconstac: Beaconstac, notification: MNotification) {\n    // If you override, you should handle everything from configuring, triggering and displaying of the notification.\n}\n```\n\n```objective-c\n\n// In the class where you want to listen to notification events...\nNSError *error = nil;\nBeconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:\u0026error];\nbeaconstacInstance.notificationDelegate = self;\n\n- (void)overrideNotification:(Beaconstac * _Nonnull)beaconstac notification:(MNotification * _Nonnull)notification {\n    // If you override, you should handle everything from configuring, triggering and displaying of the notification.\n}\n```\n\n9. Implement `WebhookDelegate` protocol methods to add additional parameters to be sent to the webhook.\n\n```swift\n// In the class where you want to listen to webhook events...\nbeaconstacInstance = try! Beaconstac.sharedInstance()\nbeaconstacInstance.webhookDelegate = self\n\nfunc addParameters(_ beaconstac: Beaconstac, webhook: MWebhook) -\u003e Dictionary\u003cString, Any\u003e {\n    // If you override, make sure the keys of the previously added ones\n}\n```\n\n```objective-c\n\n// In the class where you want to listen to notification events...\nNSError *error = nil;\nBeconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:\u0026error];\nbeaconstacInstance.webhookDelegate = self;\n\n- (NSDictionary\u003cNSString *, id\u003e * _Nonnull)addParameters:(Beaconstac * _Nonnull)beaconstac webhook:(MWebhook * _Nonnull)webhook {\n    // If you override, make sure the keys of the previously added ones\n}\n```\n\n10. The `Latch_Latency`, defines how the campOn/campOff behaviour is adjusted when the SDK finds the beacon. Lets say, the SDK camped on to a beacon and there is a beacon who's latest RSSI, is less than the latest RSSI of the camped On beacon + the latch latency, then SDK camps off from the current beacon and camps on to this beacon.\n\n```swift\nbeaconstacInstance = try! Beaconstac.sharedInstance()\nbeaconstacInstance.latchLatency = HIGH\n```\n\n```objective-c\nNSError *error = nil;\nBeconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:\u0026error];\nbeaconstacInstance.latchLatency = LatchLatencyHIGH;\n```\n\n11. If you don't listen to the `NotificationDelegate` protocol, the SDK configures, triggers UNNotification. However to present the notification do the following.\n\n```swift\n\n// Check if the notification is from SDK and provide UNNotificationPresentationOptions or nil by invoking the below method.\npublic func notificationOptionsForBeaconstacNotification(_ notification: UNNotification) -\u003e UNNotificationPresentationOptions?\n\n\n// EXAMPLE:\nfunc userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -\u003e Void) {\n    var notificationPresentationOptions: UNNotificationPresentationOptions\n    if let notificationOption = try! beaconstac.sharedInstance().notificationOptionsForBeaconstacNotification(notification) {\n      notificationPresentationOptions = notificationOption\n    } else {\n      // My Presenation options...\n    }\n    completionHandler(notificationPresentationOptions)\n}\n\n\n\n// Check if SDK can handle the notification by invoking the below method.\npublic func showCardViewerForLocalNotification(_ notification: UNNotification) -\u003e Bool\n\n\n// EXAMPLE:\nfunc userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -\u003e Void) {\n    let notification = response.notification\n    if beaconstac.showCardViewerForLocalNotification(notification) {\n        // We will handle the notification...\n    } else {\n        // Handle it...\n    }\n    completionHandler()\n}\n\n```\n\n```objective-c\n\n// Check if the notification is from SDK and provide UNNotificationPresentationOptions or nil by invoking the below method.\n- (UNNotificationPresentationOptions)notificationOptionsForBeaconstacNotification:(UNNotification *)notification;\n\n// EXAMPLE:\n- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {\n    UNNotificationPresentationOptions notificationPresentationOptions;\n    \n    NSError *error;\n    Beaconstac *i = [Beaconstac sharedInstanceAndReturnError:\u0026error];\n    \n    int option = [i notificationOptionsForBeaconstacNotification:notification];\n    \n    if (option != 0) {\n        notificationPresentationOptions = (UNNotificationPresentationOptions)option;\n    } else {\n        // My Presenation options...\n    }\n    \n    completionHandler(notificationPresentationOptions);\n}\n\n\n\n// Check if SDK can handle the notification by invoking the below method.\n- (BOOL)showCardViewerForLocalNotification:(UNNotification * _Nonnull)notification;\n\n\n// EXAMPLE:\n- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {\n    UNNotification *notification = response.notification;\n    if ([i showCardViewerForLocalNotification:notification]) {\n        // We will handle the notification...\n    } else {\n        // Handle it...\n    }\n    completionHandler();\n}\n\n```\n\n12. You are required to `add filters` regarding the app user, if the marketer has provided the filters. To do so\n\n```swift\n// Provide the filters to the SDK as Key-Value pairs using dictionary. Note keys are case insensitive.\nfunc addFilters(_ filters: Dictionary\u003cString, Any\u003e)\n```\n\n```objective-c\n// Provide the filters to the SDK as Key-Value pairs using dictionary. Note keys are case insensitive.\n- (void)addFilters:(NSDictionary\u003cNSString *, id\u003e * _Nonnull)filters;\n```\n__Note__: If the rule contains the filters and app doesn't provide it, the rule will be treated as a filter validation failed and we won't trigger that particular rule.\n\n13. The SDK collects `analytics` regarding how we collect the `iBeacon` related information and tie it to app user(MVisitor). If you know information about your app user, create a MVisitor object and provide it to us.\n\n```swift\n// If you know the your app visitor, create a Visitor object and call this on the Beaconstac instance.\nfunc setVisitor(_ visitor: MVisitor)\n```\n\n```objective-c\n// If you know the your app visitor, create a Visitor object and call this on the Beaconstac instance.\n- (void)setVisitor:(MVisitor * _Nonnull)visitor;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeaconstac%2Fios-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeaconstac%2Fios-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeaconstac%2Fios-sdk/lists"}