Installation

Android

Add the SDK dependency to your module’s build.gradle.kts:

dependencies {
    implementation("com.bagid:bagid-sdk:<version>")
}

The SDK is published to Maven Central as com.bagid:bagid-sdk-android. Transitive dependencies (including bagid-api-client-android) are resolved automatically.

Minimum requirements

  • minSdk: 29 (Android 10)

  • compileSdk: 36

  • Kotlin 2.0+

  • Managed BLE flow: rely on manifest merge from the SDK AAR so com.bagid.sdk.ui.ManagedBleFlowActivity is registered (see Managed BLE Operations — Android). If merging is disabled, declare that <activity> in your app manifest.

iOS

Add the SDK via Swift Package Manager from the public distribution repository:

https://github.com/bagid/bagid-ios-sdk

In Xcode: File → Add Package Dependencies… and paste the URL above. Select the release version that matches your integration (see Changelog).

The package provides two library products for partner apps:

Product Purpose

BagIdSDK

KMP core — BagIdSdk, models, programmatic BLE/HTTP APIs

BagIdSDKUI

SwiftUI managed BLE flow — BagIdIosHost.presentManagedBleFlow (equivalent to Android ManagedBleFlowActivity)

In Xcode, add the package dependency and link both products to your app target when using the recommended managed BLE path.

The BagIdSDK binary is a pre-built XCFramework generated from the Kotlin Multiplatform SDK.

Minimum requirements

  • iOS 16+

  • Swift 5.9+

  • Xcode 15+

  • Physical device for BLE development and testing (CoreBluetooth does not provide full BLE peripheral access in the simulator)

  • Managed BLE flow: link BagIdSDKUI and launch via BagIdIosHost — same operation/payload/result JSON contract as Android (see Managed BLE Operations)

Kotlin to Swift architecture

The SDK core is implemented in Kotlin Multiplatform. On iOS:

  • Kotlin APIs are exposed to Swift through SKIE-generated bridges

  • Coroutines and Flow map to Swift async patterns

  • The delivered artifact is an XCFramework consumed through SPM

  • Managed BLE UI is native SwiftUI in BagIdSDKUI, calling into BagIdSDK

Android: ProGuard / R8

If your Android build enables code shrinking (R8 or ProGuard), add the following rules to your proguard-rules.pro to prevent SDK classes from being stripped or renamed:

# BagID SDK — keep public facade and models
-keep class com.bagid.sdk.BagIdSdk { *; }
-keep class com.bagid.sdk.models.** { *; }
-keep class com.bagid.sdk.host.** { *; }
-keep class com.bagid.sdk.ui.ManagedBleFlowActivity { *; }

# BagID API client — keep generated Ktor/kotlinx.serialization DTOs
-keep class com.bagid.sdk.model.** { *; }
-keepclassmembers class com.bagid.sdk.model.** { *; }

# kotlinx.serialization (required by the API client)
-keepattributes *Annotation*
-dontwarn kotlinx.serialization.**
-keep @kotlinx.serialization.Serializable class * { *; }

# Ktor
-dontwarn io.ktor.**
-keep class io.ktor.** { *; }

The SDK AAR ships a bundled consumer-rules.pro file that covers the most common keep rules. The entries above are a safety net for builds with aggressive shrinking or for custom SDK configurations. If you see ClassNotFoundException or NoSuchMethodException at runtime in a release build, enable verbose R8 logging (-printusage usage.txt) to identify which class is being removed.

Bluetooth permissions

The SDK does not handle BLE permissions or Bluetooth state UI for programmatic scanForEbtTags(). Managed BLE Operations prompts for BLE access inside the full-screen surface; your app must still declare the platform permissions below.

Android

Declare in AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!-- Required on Android < 12 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Request permissions at runtime before scanning (managed flow requests them when launched, but declaring them is required):

val permissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
    arrayOf(Manifest.permission.BLUETOOTH_SCAN, Manifest.permission.BLUETOOTH_CONNECT)
} else {
    arrayOf(Manifest.permission.ACCESS_FINE_LOCATION)
}

iOS

Add to Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Required to communicate with BagID baggage tags</string>

Bluetooth state handling

Provide user-facing feedback when Bluetooth is unavailable, turned off, or unauthorized. The SDK emits scan errors, but it is the partner app’s responsibility to guide the user.

What’s next