Nodle SDK - iOS Integration
Integrating the Nodle SDK into your iOS app is easy and straightforward. Just follow the steps below and you should be ready to go in no time.

Step 1: Generate Public Key

Step 2: Install the SDK

Install the SDK via Cocoapods:
Install CocoaPods. If you don't have an existing Podfile, run pod init in your project directory. Add the following to your Podfile:
NodleSDK
NodleSDK without CoreBluetooth
1
pod 'NodleSDK'
Copied!
1
pod 'NodleSDKWCB', :podspec => 'https://raw.githubusercontent.com/NodleCode/NodleSDK-Release/main/NodleSDKWCB.podspec'
Copied!
The latest version of the stable-production SDK is 0.0.13 We recommend to add the following dependency which should be automatically pulled but if you encounter any issues you can add them to your Podfile like this:
1
# Pods for NodleSDK
2
pod 'SQLite.swift', '~> 0.13.2'
3
pod 'SwiftCBOR', '~> 0.4.5'
4
pod 'SwiftProtobuf', '~> 1.19.0'
Copied!
Then, run pod install. You may also need to run pod install --repo-update.
Add the SDK manually:
You can also add the SDK to your project manually. Download the current release, unzip the package, and drag the version of the SDK that you want use for example the version with CoreBluetooth NodleSDK.xcframework into your Xcode project. It will automatically appear in the Frameworks, Libraries, and Embedded Content section of your target settings. Switch Do Not Embed to Embed & Sign.
We recommend to add the following dependency which should be automatically pulled but if you encounter any issues you can add them to your Podfile like this:
1
# Pods for NodleSDK
2
pod 'SQLite.swift', '~> 0.13.2'
3
pod 'SwiftCBOR', '~> 0.4.5'
4
pod 'SwiftProtobuf', '~> 1.19.0'
Copied!
Then, run pod install. You may also need to run pod repo update. If you run into trouble with pod please install cocoapods-deintegrate and run pod deintegrate and also you would need to remove your cache we recommend you do the following:
1
rm -rf ~/Library/Caches/CocoaPods; rm -rf Pods; rm -rf ~/Library/Developer/Xcode/DerivedData/*; pod deintegrate;
Copied!
Then make sure you are using one of the latest cocoapods versions 1.11+ due to issues with cocoapods not picking dependency properly you need to set the following script on top of your Podfile. You can find example Podfile below:
1
post_install do |installer|
2
installer.pods_project.targets.each do |target|
3
target.build_configurations.each do |config|
4
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
5
end
6
end
7
end
8
9
# If any errors for example dyld: Symbol not found please use pod deintegrate and pod install again. You should remove your
10
# Podfile.lock and workspace and let cocoapods generate it for you if you are having
11
# trouble. Make sure you close and open the workspace when you are doing all above before
12
# pod install again.
13
platform :ios, '13.0'
14
​
15
# use_modular_headers!
16
​
17
target 'YourTarget' do
18
# Comment the next line if you don't want to use dynamic frameworks
19
use_frameworks!
20
​
21
# Pods for TestApp
22
pod 'NodleSDK'
23
pod 'SQLite.swift', '~> 0.13.2'
24
pod 'SwiftCBOR', '~> 0.4.5'
25
pod 'SwiftProtobuf', '~> 1.19.0'
26
​
27
end
Copied!
You could do the same manually by adding the ['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' to your Pod project settings. If you are on older version of cocoapods before 1.9- you will not need to do anything and you can simply proceed to next steps.
NodleSDK issues with dependencies:
If you are experiencing issues please make sure the correct version of the dependencies are in your Podfile.lock as an example with our latest version of the dependencies found here:
1
SQLite.swift: 4fc2be46c36392e3b87afe6fe7f1801c1daa07ef
2
SwiftCBOR: ac340b74d3b2cf1f8884bb748bd09875848e3873
3
SwiftProtobuf: 6ef3f0e422ef90d6605ca20b21a94f6c1324d6b3
Copied!
If you are having trouble with the dependencies loading for older versions of our SDK please make sure they are corrected in the Podfile.lock file. Example for older versions of dependencies:
1
SQLite.swift: 4fc2be46c36392e3b87afe6fe7f1801c1daa07ef
2
SwiftCBOR: ce5354ec8b660da2d6fc754462881119dbe1f963
3
SwiftProtobuf: c3c12645230d9b09c72267e0de89468c5543bd86
Copied!
After you have corrected them in the file to the correct versions and CHECKSUMS simply run pod install.
NodleSDK requirements:
We are currently using the following setup:
1
cocoapods: 1.10+
2
swift: 5+
3
XCode: 12.5.1 and above
4
build-system: New Build System
5
ios: 13.0+
Copied!

Step 3: Add the NodleSDK dependency

The SDK depends on Apple's CoreLocation, CoreBluetooth framework. In your target settings, go to General > Frameworks, Libraries, and Embedded Content and add CoreLocation, CoreBluetooth if you haven't already. If you are using the build without CoreBluetooth you will need to add only CoreLocation

Step 4: Initialize the Nodle SDK

First you need to init the NodleSDK in your AppDelegate like below:
Swift
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
import CoreBluetooth
8
​
9
@main
10
class AppDelegate: UIResponder, UIApplicationDelegate {
11
let nodle = Nodle.sharedInstance
12
}
Copied!
Or you can initialize the NodleSDK in your ViewController like below:
Swift
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
import CoreBluetooth
8
​
9
class ViewController: UIViewController, CLLocationManagerDelegate, CBCentralManagerDelegate {
10
private let locationManager = CLLocationManager()
11
var centralManager: CBCentralManager?
12
let nodle = Nodle.sharedInstance
13
}
Copied!
Then you can proceed to next steps below. Please make sure that you have added and request all permissions and dependency before you run the SDK.

Step 5: Run the Nodle SDK

In the AppDelegate or ViewController you can start Nodle by giving it your public key in the following format ss58:public_key generated in Step 1:
Swift
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
import CoreBluetooth
8
​
9
// start the sdk
10
Nodle().start("ss58:public_key");
Copied!
You can find more info here: Nodle SDK - iOS API and Configuration​

Step 6: Request Permissions

Before requesting permissions, you must add location usage strings to your Info.plist file. We require a couple permissions and they have to be added like below:
1
// NodleSDK
2
NSBluetoothAlwaysUsageDescription - Need for our bluetooth scan
3
NSBluetoothPeripheralUsageDescription - Need for our bluetooth scan
4
NSLocationAlwaysUsageDescription - Need for our location request from the background
5
NSLocationAlwaysAndWhenInUseUsageDescription - Need for our location request from background
6
NSLocationWhenInUseUsageDescription - Need for our location request
7
NSLocationUsageDescription - Need to be able to perform additional changes to
8
location while in the background.
9
​
10
// NodleSDKWCB
11
NSLocationAlwaysUsageDescription - Need for our location request from the background
12
NSLocationAlwaysAndWhenInUseUsageDescription - Need for our location request from the background
13
NSLocationWhenInUseUsageDescription - Need for our location request
14
NSLocationUsageDescription - Need to be able to perform additional changes to
15
location while in the background.
Copied!
Here is a small example how it should look like when configured:
The NodleSDK require Bluetooth and Location permissions to be added before it is started. The NodleSDKWCB doesn't require Bluetooth. Then you can proceed to next step and request permissions for Location and Bluetooth via one of the two approaches listed below depending on your choice:
Request permissions manually for NodleSDK without any third party:
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
import CoreBluetooth
8
​
9
class ViewController: UIViewController, CLLocationManagerDelegate, CBCentralManagerDelegate {
10
private let locationManager = CLLocationManager()
11
var centralManager: CBCentralManager?
12
let nodle = Nodle.sharedInstance
13
14
override func viewDidLoad() {
15
super.viewDidLoad()
16
// Do any additional setup after loading the view.
17
18
// set manager for permissions
19
locationManager.delegate = self
20
21
// check status for location permission
22
switch CLLocationManager.authorizationStatus() {
23
case .authorizedWhenInUse, .authorizedAlways:
24
// request always auth if you would use it in the background
25
locationManager.requestAlwaysAuthorization()
26
// ask for bluetooth permissions
27
centralManager = CBCentralManager(delegate: self, queue: nil)
28
case .notDetermined:
29
// ask for permissions if background otherwise use whenInUse
30
locationManager.requestAlwaysAuthorization()
31
default:
32
print("Location permission denied")
33
break;
34
}
35
}
36
37
func startNodle() {
38
// start the sdk
39
nodle.start(devKey: "ss58:5FUfDdHhtn5Bzgte69zr1NyNRS7zFqy7CnjVcRUUpWpXz3Cv", tags: "","")
40
}
41
42
func stopNodle() {
43
// stop the sdk
44
nodle.stop()
45
}
46
47
func centralManagerDidUpdateState(_ central: CBCentralManager) {
48
switch central.state {
49
case .poweredOn:
50
// start Nodle after Bluetooth permissions have been granted
51
startNodle()
52
break
53
case .poweredOff:
54
// stop nodle
55
stopNodle()
56
break
57
default:
58
break
59
}
60
}
61
62
func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
63
// handle success
64
if status == .authorizedWhenInUse || status == .authorizedAlways {
65
print("Location permission have been granted")
66
// ask for ble permissions
67
centralManager = CBCentralManager(delegate: self, queue: nil)
68
}
69
}
70
}
Copied!
Request permissions manually for NodleSDKWCB without any third party:
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
​
8
class ViewController: UIViewController, CLLocationManagerDelegate {
9
private let locationManager = CLLocationManager()
10
let nodle = Nodle.sharedInstance
11
12
override func viewDidLoad() {
13
super.viewDidLoad()
14
// Do any additional setup after loading the view.
15
16
// set manager for permissions
17
locationManager.delegate = self
18
19
// check status for location permission
20
switch CLLocationManager.authorizationStatus() {
21
case .authorizedWhenInUse, .authorizedAlways:
22
// request always auth if you would use it in the background
23
locationManager.requestAlwaysAuthorization()
24
case .notDetermined:
25
// ask for permissions if background otherwise use whenInUse
26
locationManager.requestAlwaysAuthorization()
27
default:
28
print("Location permission denied")
29
break;
30
}
31
}
32
33
func startNodle() {
34
// start the sdk
35
nodle.start(devKey: "ss58:5FUfDdHhtn5Bzgte69zr1NyNRS7zFqy7CnjVcRUUpWpXz3Cv", tags: "","")
36
}
37
38
func stopNodle() {
39
// stop the sdk
40
nodle.stop()
41
}
42
43
func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
44
// handle success
45
if status == .authorizedWhenInUse || status == .authorizedAlways {
46
print("Location permission have been granted")
47
// start Nodle after Location permissions have been granted
48
startNodle()
49
} else {
50
// stop nodle if permissions revoked
51
stopNodle()
52
}
53
}
54
}
Copied!
Request permissions via third party - SPPermissions
We recommend the SPPermissions third party library to request permissions:
1
// MARK: 1. Choose the permissions you need:
2
​
3
let permissions: [SPPermissions.Permission] = [.location, .bluetooth]
4
​
5
// MARK: 2. Choose present style:
6
​
7
// 2a. List Style
8
let controller = SPPermissions.list(permissions)
9
controller.present(on: self)
10
​
11
// 2b. Dialog Style
12
let controller = SPPermissions.dialog(permissions)
13
controller.present(on: self)
14
​
15
// 2c. Native Style
16
let controller = SPPermissions.native(permissions)
17
controller.present(on: self)
18
​
19
// MARK: 3. Optional: Check permission state (available `authorized`, `denied`, `notDetermined`):
20
​
21
let authorized = SPPermissions.Permission.calendar.authorized
Copied!
Please follow their guide how to install and setup the request. After permissions are requested and given the NodleSDK should work as expected.
And there you have it! You’re good to go!

Step 7: Run Nodle SDK in Background (Optional)

With our latest update NodleSDK is able to perform background scanning. In order to work please make sure to allowAlwaysAuthorization for background permissions and Background Modes. Then the SDK will then be working in the background for you. You can chose one of the modes that you would want to adopt or you can disable it. Depending on the permissions that are allowed the SDK will be able to perform different actions in each of the modes.
Enabling background modes - required
The NodleSDK requires certain Background Modes to be enabled in order to perform background scanning. Here is example of the ones you need to enable:
You don't have to register and schedule background tasks for the SDK but you must enable the option in some of the modes that we require. Please head out to our configuration page here: Nodle SDK - iOS API and Configuration
Improved background scanning with Background Tasks
If you want to improve the background scanning because you have chosen a specific mode. You can allow Nodle to perform some background tasks for you when possible. You must add the following task: io.nodle.sdk.ios.bgrefresh to your Info.plist file under the section: BGTaskSchedulerPermittedIdentifiers Here is a small example how it should look like when configured:
Then make sure you enabled all permissions that are required. You can proceed to register the NodleBackgroundTask by doing the following in you AppDelegate application method:
Swift
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
import CoreBluetooth
8
​
9
@main
10
class AppDelegate: UIResponder, UIApplicationDelegate {
11
// init nodle sdk
12
let nodle = Nodle.sharedInstance
13
​
14
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
15
// register background task for nodle sdk
16
nodle.registerNodleBackgroundTask()
17
return true
18
}
19
}
Copied!
Then you can proceed to schedule your tasks once your application enters background by doing the following:
Swift
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
import CoreBluetooth
8
​
9
@main
10
class AppDelegate: UIResponder, UIApplicationDelegate {
11
// init nodle sdk
12
let nodle = Nodle.sharedInstance
13
​
14
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
15
// register background task for nodle sdk
16
nodle.registerNodleBackgroundTask()
17
return true
18
}
19
20
func applicationDidEnterBackground(_ application: UIApplication) {
21
// schedule background task for nodle sdk
22
nodle.scheduleNodleBackgroundTask()
23
}
24
}
Copied!
If you are using SceneDelegates don't forget to add the following call to your delegate method by doing the following:
Swift
1
import UIKit
2
​
3
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
4
func sceneDidEnterBackground(_ scene: UIScene) {
5
// call app delegate method
6
(UIApplication.shared.delegate as? AppDelegate)?.applicationDidEnterBackground((UIApplication.shared))
7
}
8
}
Copied!
You have successfully configured the NodleSDK to perform background scanning.

Want to check your SDK rewards?

Currently we have our dashboard under development and rewards are not available. If you want see your rewards we have a workaround for you to do that. Please follow the steps:
You should see something like this if you have setup the extension properly:
  • Then you should see you dummy accountId
  • Click on the dummy accountId and paste your public_key
  • Then you should only see your public_key
  • Then click the green + on the right of the screen
  • Wait a second your rewards should be shown soon
That's it you should see your rewards. Make sure to add all permissions to the SDK in order to see your rewards. We have a lot of traffic so please bear with us since rewards might take a bit of time. But if you allow all the rules in SDK you should see the packets coming to the dashboard. Then rewards should be visible.