Skip to main content

iOS SDK - API and Configuration

The SDK receives configuration remotely from Nodle servers as well as statically using API calls. The static configuration always takes precedence over the remote configuration.

Nodle SDK Api

To interact with the SDK you need to call the Nodle.sharedInstance method that will give you an Instance of the INodle class. The following are all the public methods for the Nodle API.

Swift

import UIKit
import SwiftCBOR
import SwiftProtobuf
import NodleSDK
import SQLite
import CoreLocation
import CoreBluetooth

let nodle = Nodle.sharedInstance

start

public func start(public_key: String)

Immediately starts the Nodle SDK

Parameters
public_keyThe application public_key created in Step 1

Example:

Swift

Nodle().start("ss58:public_key")

isStarted

public func isStarted() -> Bool

Checks if the Nodle SDK is started

Parameters
booleantrue if the Nodle SDK is started, false otherwise

Example:

Swift

let sdkStarted = Nodle().isStarted()

isScanning

public func isScanning() -> Bool

Checks if the Nodle SDK is currently scanning the BLE neighborhood. This is useful if you want to show that the SDK is working.

Parameters
booleantrue if the Nodle SDK is scanning, false otherwise

Example:

Swift

let sdkScanning = Nodle().isScanning()

stop

public func stop()

Immediately stops the Nodle SDK

Example:

Swift

Nodle().stop()

clear

public func clear()

Clear any configs by Nodle SDK

Example:

Swift

Nodle().clear()

getVersion

public func getVersion() -> String

Get the version identifier of the Nodle SDK.

Parameters
Stringthe current version of the Nodle SDK

Example:

Swift

let nodleSdkVersion = Nodle().getVersion()

getEvents

public func getEvents() -> NodleEvent

Get the raw bluetooth events from the Nodle SDK with the following type:

Returns
NodleEventType.BlePayloadEventReturns NodleBluetoothScanRecord
NodleEventType.BleStartSearchingReturns NodleBluetoothEvent
NodleEventType.BleStopSearchingReturns NodleBluetoothEvent
NodleEventType.BeaconPayloadEventReturns NodleBeaconScanRecord
NodleEventType.BeaconStartSearchingReturns NodleBeaconEvent
NodleEventType.BeaconStopSearchingReturns NodleBeaconEvent

Example of available return event classes below:

Returns
NodleBluetoothScanRecordRaw Bluetooth Record from Nodle SDK
NodleBluetoothEventBluetooth Event when the SDK start/stop
NodleBeaconScanRecordRaw Beacon Record from Nodle SDK
NodleBeaconEventBeacon Event when the SDK start/stop

Example:

NodleSDK - Swift

nodle.getEvents { event in
// collect the NodleEvent events by chosing a type
switch event.type {
case .BlePayloadEvent:
let payload = event as! NodleBluetoothRecord
print("Bluetooth payload available \(payload.device)")
break
case .BleStartSearching:
print("Bluetooth started searching")
break
case .BleStopSearching:
print("Bluetooth stopped searching")
break
@unknown default:
print("Failed to get any event")
}
}

NodleSDKWCB - Swift

nodle.getEvents { event in
// collect the NodleEvent events by chosing a type
switch event.type {
case .BeaconPayloadEvent:
let payload = event as! NodleBeaconRecord
print("iBeacon payload available \(payload.identifier) major: \(payload.major) minor: \(payload.minor) delivered at \(Date())")
break
case .BeaconStartSeaching:
print("iBeacon started searching \(Date())")
break
case .BeaconStopSearching:
print("iBeacon stop searching \(Date())")
break
@unknown default:
print("Failed to get any event")
}
}

The following data can be collected from the NodleEventType:

KeyDescriptionDefault Value
typereturns nodle bluetooth event typeNodleEventType

The following data can be collected from the NodleBluetoothScanRecord:

KeyDescriptionDefault Value
devicereturns device unique identifierString
rssireturns received signal strength indicatorInt
bytesreturns raw bytes of the record[UInt8]
manufacturerSpecificDatareturns the manufacturer specific data associated with the manufacturer id[Int : [UInt8]]
servicesUuidsreturns an array of services UUID's within the advertisementArray<CBUUID>

The following data can be collected from the NodleBluetoothEvent:

KeyDescriptionDefault Value
scanningreturns bluetooth scanning stateBool

The following data can be collected from the NodleBeaconScanRecord:

KeyDescriptionDefault Value
identifierreturns device unique identifierString
majorreturns major value of the beaconNSNumber
minorreturns minor value of the beaconNSNumber
proximityreturns proximity value of the beaconInt
accuracyreturns accuracy value of the beaconDouble
rssireturns received signal strength value of the beaconInt

The following data can be collected from the NodleBeaconEvent:

KeyDescriptionDefault Value
scanningreturns beacon scanning stateBool

The table shows rational range for the beacon devices that are found:

KeyDescriptionRange
proximityIntunknown = 0, immediate = 1, near = 2, far = 3
accuracyDoubleunknown 0, 0 - 0.5 immediate, 0.5 - 3 near, 3+ far in meters
rssiInt-128

registerNodleBackgroundTask

public func registerNodleBackgroundTask()

Register the Nodle SDK background task

Example:

Swift

Nodle().registerNodleBackgroundTask()

scheduleNodleBackgroundTask

public func scheduleNodleBackgroundTask()

Schedules the Nodle SDK background task

Example:

Swift

Nodle().scheduleNodleBackgroundTask()

config

public func config(path: Path)

public func <T> config(key: String, value: T)

configure the SDK either by supplying a json file located in ../config.json or by directly configuring a key. An example of a json configuration look like this:

{
"ble": {
"scan": {
"duration-msec": 10000,
"interval-msec": 90000,
"interval-x-factor": 1
}
},
"dtn": {
"use-cellular": false
}
}

the following are the table of all the keys available and their description:

KeyDescriptionDefault Value
ble.scan.duration-msecduration of a single ble pass in milliseconds. Longer scan increase battery consumption but gives more reward.10000
ble.scan.interval-msecwait time between two ble pass in milliseconds. Longer period reduce battery consumption but gives less reward90000
ble.scan.interval-x-factormultiplier for the ble scan interval above.1
dtn.use-cellularif true, the cellular connexion will be used. if false, only wifi connection will be used.true
cron.ios-bg-modeIf specified, the SDK will run in the specific background mode that it is selected.2
cron.ios-bg-mode-distance-metersIf specified, the SDK will trigger background scans for Normal mode depending on the meters that are specified with this option.20

there is another table that will allow you to configure our SDK background modes. There are 4 available modes: NONE, ECO, NORMAL, AGGRESSIVE for the NodleSDK please check them in the table below:

KeyDescriptionDefault Value
NONEThe SDK will run in foreground mode only. You don't need to give allowAlways permissions. WhileInUse is enough for this mode. You may wish to only use Background Tasks for this mode.0
AGGRESSIVEThe SDK will run in aggressive mode that require all permissions we requested to allowAlways. Then you have to enable Background Modes as well. There is no need to register Background Tasks for this mode. This mode will work even when the phone is with locked screen. This mode will keep the SDK awake without suspending it. Once terminated it won't be able to restore it.1
NORMALThe SDK will run in normal mode that require all permissions we requested to allowAlways since it still runs in the background. Then you have to enable Background Modes as well. This mode will be a bit less aggressive than the previous mode. It will trigger when there are location changes. You can change the distance with the config option. You may wish to combine Background Tasks for this mode. This mode will work even when the phone is with locked screen. This mode will be able to awake the SDK after it's fully suspended. Once terminated it won't be able to restore it.2
ECOThe SDK will run in eco mode that require all permissions we requested to allowAlways since it still runs in the background. Then you have to enable Background Modes as well. This mode will provide a very limited background work. It will trigger really rarely in the background. And when there are location changes. You may wish to combine Background Tasks for this mode. This mode will work even when the phone is with locked screen. This mode will be able to awake the SDK after it's fully suspended and even terminated.3

Example:

Swift

import UIKit
import SwiftCBOR
import SwiftProtobuf
import NodleSDK
import SQLite
import CoreLocation
import CoreBluetooth

// load the json config located in your app folder config.json
let bundle = Foundation.Bundle(identifier: "io.nodle.apptest.AppTest")

// path for the file in the project
let path = bundle!.path(forResource: "config", ofType: "json")

// or you can manually set the entries, for instance
Nodle().config("dtn.use-cellular", false);

// background mode selected - foreground only
Nodle().config("cron.ios-bg-mode", 0);

// then proceed to start Nodle
Nodle().start()