Skip to content

Mobile ID SDK API reference

Overview

This document provides a complete API reference for the BALTECH Mobile ID SDK. The SDK enables mobile devices to act as secure credentials for access control applications via Bluetooth Low Energy (BLE).

Each section below documents a public class, data structure, or type with signatures for both Kotlin and Swift.

Reader

Represents a smartcard reader when working in "Remote" mode.

Description

Each reader object represents a gate connected to a physical reader. It provides the display name and a trigger function to open the gate.

Kotlin signature

data class Reader(
    val displayName: String,
    val trigger: () -> Unit
)

Swift signature

public class Reader {
    public let displayName: String
    public let trigger: () -> Void
}

Properties

displayName

The name of the gate connected to this reader.

Kotlin: 

val displayName: String

Swift: 

public let displayName: String

trigger

A callback to open the gate connected to this reader.

Kotlin: 

val trigger: () -> Unit

Swift: 

public let trigger: () -> Void

Credential

Represents the components extracted from a project key for Mobile ID operations.

Description

A credential contains the cryptographic keys and signed credential bytes required for secure communication with BALTECH readers. Credentials are created from a project key and credential ID.

Kotlin signature

data class Credential(
    val keyComm: ByteArray,
    val keyInitblock: ByteArray,
    val credentialBytes: ByteArray,
    var onTrigger: (() -> Boolean)? = null
)

Swift signature

public class Credential {
    public let keyComm: KotlinByteArray
    public let keyInitblock: KotlinByteArray
    public let credentialBytes: KotlinByteArray
    public var onTrigger: (() -> KotlinBoolean)? = nil
}

Properties

keyComm

16-byte communication key used for secure data exchange.

Kotlin: 

val keyComm: ByteArray

Swift: 

public let keyComm: KotlinByteArray

keyInitblock

16-byte initialization block key.

Kotlin: 

val keyInitblock: ByteArray

Swift: 

public let keyInitblock: KotlinByteArray

credentialBytes

Variable-length signed credential data.

Kotlin: 

val credentialBytes: ByteArray

Swift: 

public let credentialBytes: KotlinByteArray

onTrigger

Optional callback for trigger authorization. When set, this callback is invoked before opening a gate and must return true to authorize the action. If not set, all trigger requests are authorized by default.

Kotlin: 

var onTrigger: (() -> Boolean)? = null

Swift: 

public var onTrigger: (() -> KotlinBoolean)? = nil

Companion object methods

create

Creates credential components from a project key and credential ID.

Kotlin: 

fun create(
    projectKey: ByteArray,
    credentialId: String,
    onTrigger: (() -> Boolean)? = null
): Credential

Swift: 

public class func create(
    projectKey: KotlinByteArray,
    credentialId: String,
    onTrigger: (() -> KotlinBoolean)? = nil
) -> Credential

Parameters: - projectKey: The project-wide 16-byte key - credentialId: The credential ID string - onTrigger: Optional callback for trigger authorization, defaults to null (always authorized)

Returns: A Credential object with extracted keys and signed credential

Example (Kotlin): 

val projectKey = byteArrayOf(/* 16 bytes */)
val credential = Credential.create(
    projectKey = projectKey,
    credentialId = "user123",
    onTrigger = {
        // Ask user for confirmation
        showConfirmationDialog()
    }
)

Example (Swift): 

let projectKey = KotlinByteArray(size: 16)
let credential = Credential.companion.create(
    projectKey: projectKey,
    credentialId: "user123",
    onTrigger: {
        // Ask user for confirmation
        return self.showConfirmationDialog()
    }
)

MobileIdSdk

Main SDK class that provides all functionality to support BALTECH Mobile ID.

Description

The MobileIdSdk class is the primary interface for integrating Mobile ID functionality into your application. It handles BLE communication, credential management, reader discovery, and permission handling.

Kotlin signature

class MobileIdSdk()

Swift signature

public class MobileIdSdk {
    public init()
}

Constructor

Creates a new instance of the Mobile ID SDK.

Kotlin: 

val sdk = MobileIdSdk()

Swift: 

let sdk = MobileIdSdk()

MobileIdSdk properties

debugMode

Enable or disable debug mode to print log messages to console.

Kotlin: 

var debugMode: Boolean

Swift: 

public var debugMode: Bool

Example (Kotlin): 

sdk.debugMode = true

Example (Swift): 

sdk.debugMode = true

onReadersUpdate

Callback that gets called when the list of available readers is updated.

Kotlin: 

var onReadersUpdate: (() -> Unit)?

Swift: 

public var onReadersUpdate: (() -> KotlinUnit)?

Example (Kotlin): 

sdk.onReadersUpdate = {
    println("Readers updated: ${sdk.readers.size} available")
    updateUI()
}

Example (Swift): 

sdk.onReadersUpdate = {
    print("Readers updated: \(sdk.readers.count) available")
    self.updateUI()
    return KotlinUnit()
}

onAvailabilityChange

Callback that gets called when the BLE availability status changes.

Kotlin: 

var onAvailabilityChange: ((Availability) -> Unit)?

Swift: 

public var onAvailabilityChange: ((Availability) -> KotlinUnit)?

Example (Kotlin): 

sdk.onAvailabilityChange = { availability ->
    when (availability) {
        AvailabilityStates.READY -> println("BLE ready")
        AvailabilityStates.BLUETOOTH_OFF -> println("Please enable Bluetooth")
        AvailabilityStates.PERMISSIONS_DENIED -> println("Permissions denied")
        else -> println("Status: $availability")
    }
}

Example (Swift): 

sdk.onAvailabilityChange = { availability in
    switch availability {
    case AvailabilityStates.shared.READY:
        print("BLE ready")
    case AvailabilityStates.shared.BLUETOOTH_OFF:
        print("Please enable Bluetooth")
    case AvailabilityStates.shared.PERMISSIONS_DENIED:
        print("Permissions denied")
    default:
        print("Status: \(availability)")
    }
    return KotlinUnit()
}

readers

List of currently available readers (gates).

Kotlin: 

val readers: List<Reader>

Swift: 

public var readers: [Reader] { get }

Description: Returns a list of Reader objects representing all discovered gates within BLE range. The list is empty until credentials are set and readers are discovered.

Example (Kotlin): 

sdk.readers.forEach { reader ->
    println("Reader: ${reader.displayName}")
}

Example (Swift): 

for reader in sdk.readers {
    print("Reader: \(reader.displayName)")
}

credentials

List of credentials (supports 0 or 1 element only).

Kotlin: 

var credentials: List<Credential>

Swift: 

public var credentials: [Credential]

Description: - Setting credentials to a non-empty list starts the BLE protocol - Setting to an empty list stops the BLE protocol - Only supports 0 or 1 credential (throws IllegalArgumentException if more than 1) - Setting the same credential again has no effect

Example (Kotlin): 

// Start SDK with credential
val credential = Credential.create(projectKey, "user123")
sdk.credentials = listOf(credential)

// Stop SDK
sdk.credentials = emptyList()

Example (Swift): 

// Start SDK with credential
let credential = Credential.companion.create(
    projectKey: projectKey,
    credentialId: "user123"
)
sdk.credentials = [credential]

// Stop SDK
sdk.credentials = []

availability

Current Bluetooth availability status.

Kotlin: 

val availability: Availability

Swift: 

public var availability: Availability { get }

Returns: Current availability state (e.g., READY, BLUETOOTH_OFF, PERMISSIONS_DENIED, etc.)

Example (Kotlin): 

when (sdk.availability) {
    AvailabilityStates.READY -> startScanning()
    AvailabilityStates.BLUETOOTH_OFF -> showEnableBluetoothPrompt()
    AvailabilityStates.PERMISSIONS_DENIED -> requestPermissions()
    else -> showError(sdk.availability)
}

Example (Swift): 

switch sdk.availability {
case AvailabilityStates.shared.READY:
    startScanning()
case AvailabilityStates.shared.BLUETOOTH_OFF:
    showEnableBluetoothPrompt()
case AvailabilityStates.shared.PERMISSIONS_DENIED:
    requestPermissions()
default:
    showError(sdk.availability)
}

availabilityFlow

Availability status as a Kotlin Flow for reactive programming.

Kotlin: 

val availabilityFlow: StateFlow<Availability>

Swift: 

public var availabilityFlow: Kotlinx_coroutines_coreStateFlow { get }

Description: A StateFlow that emits availability changes. Useful for reactive UI updates in Kotlin.

Example (Kotlin): 

lifecycleScope.launch {
    sdk.availabilityFlow.collect { availability ->
        updateAvailabilityUI(availability)
    }
}

Note: In Swift, prefer using the onAvailabilityChange callback instead of the Flow API.

MobileIdSdk methods

sendLogs

Send logs via email using the sharing driver.

Kotlin: 

suspend fun sendLogs(
    subject: String? = null,
    message: String? = null
)

Swift: 

public func sendLogs(
    subject: String? = nil,
    message: String? = nil,
    completionHandler: @escaping (Error?) -> Void
)

Parameters: - subject: Optional custom email subject. Defaults to "BALTECH Mobile ID support request" - message: Optional custom message to include before device information. Defaults to "Mobile ID Log Report"

Throws: IllegalStateException if no logs are available to send

Description: Opens the device's email client with a pre-filled support request email containing: - Device information (OS, OS version, device model, app version, SDK version) - Device ID - Attached log file with all SDK logs from the past hour

Example (Kotlin): 

scope.launch {
    try {
        sdk.sendLogs(
            subject = "Mobile ID Issue - Cannot open gate",
            message = "Having trouble opening the main entrance gate."
        )
    } catch (e: IllegalStateException) {
        showError("No logs available")
    }
}

Example (Swift): 

sdk.sendLogs(
    subject: "Mobile ID Issue - Cannot open gate",
    message: "Having trouble opening the main entrance gate."
) { error in
    if let error = error {
        self.showError("Failed to send logs: \(error)")
    }
}

requestPermissions

Request all required BLE permissions.

Kotlin: 

suspend fun requestPermissions(): Boolean

Swift: 

public func requestPermissions(
    completionHandler: @escaping (KotlinBoolean?, Error?) -> Void
)

Returns: true if permissions were granted, false otherwise

Description:

Note: This function is typically NOT needed, as the SDK automatically checks and requests permissions when you set the credentials property (which internally calls start()).

Use this function only when: - The user denied permissions initially and you want to manually retry the request - You want explicit control over when permission dialogs appear

Example (Kotlin): 

scope.launch {
    val granted = sdk.requestPermissions()
    if (granted) {
        println("Permissions granted")
    } else {
        println("Permissions denied")
    }
}

Example (Swift): 

sdk.requestPermissions { granted, error in
    if let granted = granted, granted.boolValue {
        print("Permissions granted")
    } else {
        print("Permissions denied")
    }
}

See Also: - openPermissionSettings() for permanently denied permissions

openPermissionSettings

Open system settings where the user can manually grant permissions.

Kotlin: 

suspend fun openPermissionSettings(): Boolean

Swift: 

public func openPermissionSettings(
    completionHandler: @escaping (KotlinBoolean?, Error?) -> Void
)

Returns: true if settings were opened successfully, false if opening failed or not supported

Description: Call this when permissions are permanently denied (user checked "Don't ask again") and you need the user to manually enable permissions in system settings.

Typical flow: 1. Check availability - if it's PERMISSIONS_PERMANENTLY_DENIED 2. Show user a dialog explaining why permissions are needed 3. Call this function to open system settings 4. User grants permissions in settings and returns to your app

Example (Kotlin): 

scope.launch {
    if (sdk.availability == AvailabilityStates.PERMISSIONS_PERMANENTLY_DENIED) {
        showDialog(
            title = "Permissions Required",
            message = "Please enable Bluetooth permissions in Settings",
            onConfirm = {
                scope.launch {
                    sdk.openPermissionSettings()
                }
            }
        )
    }
}

Example (Swift): 

if sdk.availability == AvailabilityStates.shared.PERMISSIONS_PERMANENTLY_DENIED {
    showDialog(
        title: "Permissions Required",
        message: "Please enable Bluetooth permissions in Settings"
    ) {
        sdk.openPermissionSettings { success, error in
            // Settings opened
        }
    }
}

Title