Skip to content

IDE integration guide

The SDK is hosted at https://github.com/baltech-ag/MobileIDSDK-pkg. Platform-specific SDKs are located in \sdk\ios and \sdk\android, but we recommend integrating via Swift Packager Manager or Maven Central as described below.

Android Studio integration

Prerequisites

  • Android Studio Arctic Fox (2020.3.1) or later
  • Android SDK 28 (Android 9.0) or higher
  • Kotlin 1.5+ or Java 11+

Step 1: Add SDK dependency via IDE

Option A: Using Project Structure dialog (recommended)

  1. Open your Android project in Android Studio
  2. Navigate to File → Project Structure (or press Ctrl+Alt+Shift+S / Cmd+; on Mac)
  3. Select Dependencies in the left panel
  4. Select your app module (usually named "app")
  5. Click the + button and select Library Dependency
  6. In the search field, type: de.baltech:sdk-android
  7. Select the latest version (e.g., 0.01.00)
  8. Click OK to add the dependency
  9. Click Apply and OK to close the dialog
  10. Android Studio will automatically sync your project with Gradle

Option B: Manual Gradle configuration

If you prefer manual configuration or need more control:

  1. Open your app module's build.gradle.kts file (or build.gradle for Groovy DSL)
  2. Add the dependency to the dependencies block:

Kotlin DSL (build.gradle.kts): 

dependencies {
    implementation("de.baltech:sdk-android:0.01.00")
}

Groovy DSL (build.gradle): 

dependencies {
    implementation 'de.baltech:sdk-android:0.01.00'
}

  1. Click Sync Now in the notification bar that appears

Step 2: Configure Java compatibility

  1. In the same build.gradle.kts (or build.gradle) file, locate the android block
  2. Add or update the compileOptions section:

Kotlin DSL: 

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}

Groovy DSL: 

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
}

  1. If using Kotlin, add the JVM toolchain configuration: 

    kotlin {
    jvmToolchain(11)
}

  2. Click Sync Now again

Step 3: Add required permissions

  1. In the Project panel, navigate to app/src/main/AndroidManifest.xml
  2. Add the following permissions inside the <manifest> tag (before or after the <application> tag):
<!-- Bluetooth permissions -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- Location permissions required for BLE scanning -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Android 12+ BLE permissions -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

<!-- Declare BLE hardware requirement -->
<uses-feature
    android:name="android.hardware.bluetooth_le"
    android:required="true"/>

Step 4: Verify installation

  1. Build your project by selecting Build → Rebuild Project

  2. Verify that the SDK is properly imported by checking if you can import SDK classes: 

    import de.baltech.mobileid.MobileIdSdk
import de.baltech.mobileid.Credential

  3. If the import works without errors, the SDK is successfully integrated

Troubleshooting Android Studio

Problem: Dependency not found

  • Verify that Maven Central is included in your repositories. In settings.gradle.kts (or settings.gradle), ensure: 
    dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()  // Make sure this is present
    }
}

Problem: Java version mismatch

  • Make sure your project's JDK is Java 11 or higher
  • Go to File → Project Structure → SDK Location and verify the JDK version

Problem: Sync fails

  • Check your internet connection (Maven Central requires network access)
  • Try File → Invalidate Caches / Restart
  • Check the Build output panel for specific error messages

Xcode integration

Prerequisites

  • Xcode 13.0 or later
  • iOS 13.0 or higher deployment target
  • Swift 5.5+ or Objective-C support

Step 1: Add SDK via Swift Package Manager

  1. Open your iOS project in Xcode
  2. Select your project in the Project Navigator (top-left panel)
  3. Select your app target under TARGETS
  4. Click the General tab
  5. Scroll down to Frameworks, Libraries, and Embedded Content
  6. Click the + button below the list
  7. In the dialog that appears, click Add Other → Add Package Dependency...

  8. In the search field at the top right, enter the package repository URL: 

    [https://github.com/baltech-ag/MobileIDSDK-pkg](https://github.com/baltech-ag/MobileIDSDK-pkg)

  9. Select the version requirements:

  10. Dependency Rule: Choose "Up to Next Major Version"

  11. Version: Enter the minimum version (e.g., 0.1.0)

  12. Click Add Package

  13. In the next dialog, verify that MobileIDSdk is selected for your target
  14. Click Add Package again
  15. Xcode will download and integrate the SDK

Note: If your organization distributes the SDK via a private Swift Package repository, use that URL instead.

Step 2: Configure Info.plist

Option A: Using Property List Editor (visual)

  1. In the Project Navigator, select Info.plist (usually located in your app's main folder)
  2. Right-click in the property list and select Add Row

  3. Add the following keys one by one:

    Bluetooth Always Usage Description:

     - **Key**: `Privacy - Bluetooth Always Usage Description` (Xcode will auto-complete)
 - **Type**: String
 - **Value**: `This app uses Bluetooth to communicate with access control readers for secure credential transfer.`

    Bluetooth Peripheral Usage Description: (for iOS 12 and earlier)

     - **Key**: `Privacy - Bluetooth Peripheral Usage Description`
 - **Type**: String
 - **Value**: `This app acts as a Bluetooth peripheral to transfer credentials to access control readers.`

  4. Add required device capabilities:

    • Key: Required device capabilities
    • Type: Array
    • Click the disclosure arrow and add an item:
    • Item 0: String = bluetooth-le

  5. Add background modes:

    • Key: Required background modes
    • Type: Array
    • Click the disclosure arrow and add an item:
    • Item 0: String = bluetooth-peripheral

Option B: Using Source Code Editor (raw XML)

  1. Right-click Info.plist and select Open As → Source Code
  2. Add the following XML inside the <dict> tag:
<!-- Bluetooth usage descriptions (required) -->
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to communicate with access control readers for secure credential transfer.</string>

<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app acts as a Bluetooth peripheral to transfer credentials to access control readers.</string>

<!-- Required device capabilities -->
<key>UIRequiredDeviceCapabilities</key>
<array>
    <string>bluetooth-le</string>
</array>

<!-- Background modes for BLE -->
<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-peripheral</string>
</array>
  1. Save the file and switch back to Open As → Property List for visual editing

Step 3: Configure background modes (alternative method)

  1. Select your project in the Project Navigator
  2. Select your app target
  3. Click the Signing & Capabilities tab
  4. Click + Capability at the top
  5. Search for and add Background Modes
  6. Check the box next to Uses Bluetooth LE accessories

This will automatically add the background mode to your Info.plist.

Step 4: Verify installation

  1. Build your project by pressing Cmd+B

  2. Verify that the SDK is properly imported by adding an import statement to any Swift file: 

    import MobileIDSdk

  3. Try creating an SDK instance: 

    let sdk = MobileIdSdk()

  4. If there are no build errors, the SDK is successfully integrated

Platform-specific considerations

Android

  • Minimum SDK version: Set minSdkVersion to 28 or higher in your build.gradle.kts
  • Target SDK version: Target Android 12 (API 31) or higher to support latest BLE permissions
  • ProGuard/R8: If using code obfuscation, add keep rules for SDK classes (see Advanced topics)

iOS

  • Deployment target: Set iOS Deployment Target to 13.0 or higher in your project settings
  • Physical device required: Always test on a real iPhone/iPad (Simulator doesn't support BLE)
  • Code signing: Ensure your app is properly signed for testing on devices
  • Bitcode: The SDK supports Bitcode if your project requires it
Title