> For the complete documentation index, see [llms.txt](https://nodle.gitbook.io/nodle-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nodle.gitbook.io/nodle-sdk/nodle-sdk-ios-api-and-configuration.md).

# Nodle SDK - iOS 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.

{% tabs %}
{% tab title="Swift" %}

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

let nodle = Nodle.sharedInstance
```

{% endtab %}
{% endtabs %}

## start

**`public fun`**` ``start(public_key:`` `**`String`**`)`

Immediately starts the Nodle SDK

|  Parameters  |                                               |
| :----------: | --------------------------------------------- |
| `public_key` | The application public\_key created in Step 1 |

Example:

{% tabs %}
{% tab title="Swift" %}

```java
Nodle().start("ss58:public_key");
```

{% endtab %}
{% endtabs %}

## isStarted

**`public fun`**` ``isStarted():`` `**`Boolean`**

Checks if the Nodle SDK is started

|  Returns  |                                                           |
| :-------: | --------------------------------------------------------- |
| `boolean` | **true** if the Nodle SDK is started, **false** otherwise |

Example:

{% tabs %}
{% tab title="Swift" %}

```java
let sdkStarted = Nodle().isStarted()
```

{% endtab %}
{% endtabs %}

## isScanning

**`public fun`**` ``isScanning():`` `**`Boolean`**

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

|  Returns  |                                                            |
| :-------: | ---------------------------------------------------------- |
| `boolean` | **true** if the Nodle SDK is scanning, **false** otherwise |

Example:

{% tabs %}
{% tab title="Swift" %}

```java
let sdkScanning = Nodle().isScanning()
```

{% endtab %}
{% endtabs %}

## stop

 **`public fun`**` ``stop()`

Immediately stops the Nodle SDK

Example:

{% tabs %}
{% tab title="Swift" %}

```java
Nodle().stop();
```

{% endtab %}
{% endtabs %}

## clear

 **`public fun`**` ``clear()`

Clear any configs by Nodle SDK

Example:

{% tabs %}
{% tab title="Swift" %}

```java
Nodle().clear();
```

{% endtab %}
{% endtabs %}

## getVersion

**`public fun`**` ``getVersion():`` `**`String`**

Get the version identifier of the Nodle SDK.

|  Returns |                                      |
| :------: | ------------------------------------ |
| `String` | the current version of the Nodle SDK |

Example:

{% tabs %}
{% tab title="Swift" %}

```java
let nodleSdkVersion = Nodle().getVersion();
```

{% endtab %}
{% endtabs %}

## getEvents

**`public fun`**` ``getEvents():`` `**`NodleEvent`**

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

<table data-header-hidden><thead><tr><th width="377.1734027028742" align="center">Returns</th><th></th></tr></thead><tbody><tr><td align="center">Returns</td><td></td></tr><tr><td align="center"><code>NodleEventType.BlePayloadEvent</code></td><td>Returns NodleBluetoothScanRecord                </td></tr><tr><td align="center"><code>NodleEventType.BleStartSearching</code></td><td>Returns NodleBluetoothEvent</td></tr><tr><td align="center"><code>NodleEventType.BleStopSearching</code></td><td>Returns NodleBluetoothEvent</td></tr><tr><td align="center"><code>NodleEventType.BeaconPayloadEvent</code></td><td><p>Returns </p><p>NodleBeaconRecord</p></td></tr><tr><td align="center"><code>NodleEventType.BeaconStartSearching</code></td><td><p>Returns </p><p>NodleBeaconEvent</p></td></tr><tr><td align="center"><code>NodleEventType.BeaconStopSearching</code></td><td><p>Returns </p><p>NodleBeaconEvent</p></td></tr></tbody></table>

Example of available return event classes below:

|           Returns          |                                         |
| :------------------------: | --------------------------------------- |
| `NodleBluetoothScanRecord` | Raw Bluetooth Record from Nodle SDK     |
|    `NodleBluetoothEvent`   | Bluetooth Event when the SDK start/stop |
|   `NodleBeaconScanRecord`  | Raw Beacon Record from the Nodle SDK    |
|     `NodleBeaconEvent`     | Beacon Event when the SDK start/stop    |

Example:

{% tabs %}
{% tab title="Swift - NodleSDK" %}

```java
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")
    }
}
```

{% endtab %}

{% tab title="Swift - NodleSDKWCB" %}

```
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")
    }
}
```

{% endtab %}
{% endtabs %}

The following data can be collected from the `NodleEventType`:

| **Key** | **Description**                    | Default Value  |
| ------- | ---------------------------------- | -------------- |
| `type`  | returns nodle bluetooth event type | NodleEventType |

The following data can be collected from the `NodleBluetoothScanRecord`:

| **Key**                    | **Description**                                                            | Default Value     |
| -------------------------- | -------------------------------------------------------------------------- | ----------------- |
| `device`                   | returns device unique identifier                                           | String            |
| `rssi`                     | returns received signal strength indicator                                 | Int               |
| `bytes`                    | returns raw bytes of the record                                            | \[UInt8]          |
| `manufacturerSpecificData` | returns the manufacturer specific data associated with the manufacturer id | \[Int : \[UInt8]] |
| `servicesUuids`            | returns an array of services UUID's within the advertisement               | Array\<CBUUID>    |

The following data can be collected from the `NodleBluetoothEvent`:

| **Key**    | **Description**                  | Default Value |
| ---------- | -------------------------------- | ------------- |
| `scanning` | returns bluetooth scanning state | Bool          |

The following data can be collected from the `NodleBeaconScanRecord`:

| **Key**      | **Description**                                      | Default Value |
| ------------ | ---------------------------------------------------- | ------------- |
| `identifier` | returns device unique identifier                     | String        |
| `major`      | returns major value of the beacon                    | NSNumber      |
| `minor`      | returns minor value of the beacon                    | NSNumber      |
| `proximity`  | returns proximity value of the beacon                | Int           |
| `accuracy`   | returns accuracy value of the beacon                 | Double        |
| `rssi`       | returns received signal strength value of the beacon | Int           |

The following data can be collected from the `NodleBeaconEvent`:

| **Key**    | **Description**               | Default Value |
| ---------- | ----------------------------- | ------------- |
| `scanning` | returns beacon scanning state | Bool          |

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

| **Key**     | **Description** | **Range**                                                                        |
| ----------- | --------------- | -------------------------------------------------------------------------------- |
| `proximity` | Int             | **unknown** = 0, **immediate** = 1, **near** = 2, **far** = 3                    |
| `accuracy`  | Double          | **unknown** 0, 0 - 0.5 **immediate**, 0.5 - 3 **near**, 3+ **far** in **meters** |
| `rssi`      | Int             | -**128**\|+**127**                                                               |

## registerNodleBackgroundTask

&#x20;**`public fun`**` ``registerNodleBackgroundTask()`

Register the Nodle SDK background task

Example:

{% tabs %}
{% tab title="Swift" %}

```java
Nodle().registerNodleBackgroundTask()
```

{% endtab %}
{% endtabs %}

## scheduleNodleBackgroundTask

&#x20;**`public fun`**` ``scheduleNodleBackgroundTask()`

Schedules the Nodle SDK background task

Example:

{% tabs %}
{% tab title="Swift" %}

```java
Nodle().scheduleNodleBackgroundTask()
```

{% endtab %}
{% endtabs %}

## config

**`public fun`**` ``config(path: Path)`

**`public fun <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:

| **Key**                            | **Description**                                                                                                                      | Default Value |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `ble.scan.duration-msec`           | duration of a single ble pass in milliseconds. Longer scan increase battery consumption but gives more reward.                       | 10000         |
| `ble.scan.interval-msec`           | wait time between two ble pass in milliseconds. Longer period reduce battery consumption but gives less reward                       | 90000         |
| `ble.scan.interval-x-factor`       | multiplier for the ble scan interval above.                                                                                          | 1             |
| `dtn.use-cellular`                 | if **true**, the cellular connexion will be used. if **false**, only wifi connection will be used.                                   | true          |
| `cron.ios-bg-mode`                 | If specified, the SDK will run in the specific background mode that it is selected.                                                  | 2             |
| `cron.ios-bg-mode-distance-meters` | If 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:

| **Key**      | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Default Value |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `NONE`       | The 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             |
| `AGGRESSIVE` | The 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             |
| `NORMAL`     | The 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             |
| `ECO`        | The 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:

{% tabs %}
{% tab title="Swift" %}

```java
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()
```

{% endtab %}
{% endtabs %}