Getting started

Before you begin

This page illustrates the expected native integration flow. Supported operating systems, toolchain requirements and package instructions will be provided with the SDK release.

Code and package names below are illustrative and may change. Do not use them as production build instructions.

2. Add the Android package

Add the Android SDK package using the distribution and dependency instructions published with its release.

dependencyResolutionManagement {
    repositories {
        maven { url = uri("<local SDK repository>") }
        google()
        mavenCentral()
    }
}

dependencies {
    implementation("YOUR_SDK_GROUP:YOUR_SDK_ARTIFACT:YOUR_SDK_VERSION")
}

Request the runtime permissions required by the Android version and SDK release. Follow the Android permission guidance published with the SDK.

3. Add the iOS package

Add the iOS SDK using the package and integration instructions published with its release.

Alternatively, use the package’s local CocoaPods integration:

platform :ios, "<minimum supported version>"
use_frameworks!

target "YourApp" do
  pod "YOUR_SDK_PACKAGE", :path => "<local SDK package path>"
end

Add a meaningful NSBluetoothAlwaysUsageDescription. Observe the SDK’s Bluetooth availability event. Availability of the phone’s Bluetooth radio is separate from device readiness and headset-audio readiness.

4. Discover, select, connect

1. Create and retain one SDK client on the main thread; register event and log callbacks.
2. Obtain permissions and guide the user to enable Bluetooth.
3. Start scanning and render Discovered/discovered results.
4. Connect to the device the user selects using its discovered ID.
5. Wait for connection state ready, then issue supported device calls.
6. Release the owner by calling close() when finished.

// Import the package and client documented for the SDK release.

// Create and retain one client, on the main thread.
val sdk = ArmorDeviceClient(context.applicationContext)
sdk.onEvent = { event ->
    when (event) {
        is ArmorEvent.Discovered -> showDevice(event.device)
        is ArmorEvent.Connection -> {
            if (event.state == "ready") sdk.readBattery()
        }
        is ArmorEvent.Battery -> showBattery(event.percent)
        is ArmorEvent.Failure ->
            showError(event.error.code, event.error.operation)
        else -> Unit
    }
}

// After runtime permission approval:
sdk.startScan()
// When the user selects a discovered device:
// sdk.connect(deviceID = selectedDeviceID)
// On owner teardown, call sdk.close().

// Import the package and client documented for the SDK release.

// Create and retain one client, on the main thread.
let sdk = ArmorDeviceClient()
sdk.onEvent = { event in
    switch event {
    case .discovered(let device): showDevice(device)
    case .battery(_, let percent): showBattery(percent)
    case .failure(let error): showError(error.code, error.operation)
    default: break
    }
}

// Wait for Bluetooth availability, then scan.
sdk.startScan()
// When the user selects a discovered device:
// sdk.connect(deviceID: selectedDeviceID)
// After .connection("ready"), request sdk.readBattery().
// On owner teardown, call sdk.close().

context, showDevice, showBattery and showError are application-owned values/callbacks. These snippets illustrate integration; the package demo contains full native app setup.

5. Handle readiness and outcomes

A returned request ID identifies the call. It does not mean the device completed the action. Read results from events and correlate them by request ID. Events can arrive synchronously before a call returns; dispatch processing to the main queue when registering request IDs first.

Check feature availability before showing an operation. Preserve an unknown battery value as null/nil. Use an app-owned saved serial to validate a historical device; a matching advertised name alone is insufficient.