SDK Installation

This guide covers the installation and setup of the Kiwa eLicense Holder SDK for Android/JVM and iOS platforms.

Maven Repositories

The Kiwa SDK is distributed through Sphereon's Nexus repository at https://nexus.sphereon.com.

Open-Source Dependencies

The SDK's open-source dependencies (including the Identity Development Kit) are available in the public repositories:

• Releases: https://nexus.sphereon.com/content/repositories/sphereon-opensource-releases/
• Snapshots: https://nexus.sphereon.com/content/repositories/sphereon-opensource-snapshots/

info

Snapshot versions are development builds and are not guaranteed to be stable.

Kiwa SDK Repositories (Authenticated)

The Kiwa SDK itself is proprietary and requires authentication. Licensed customers receive Nexus credentials to access:

• Releases: https://nexus.sphereon.com/content/repositories/kiwa-releases/
• Snapshots: https://nexus.sphereon.com/content/repositories/kiwa-snapshots/

Group IDs and Artifacts

The Kiwa SDK uses the following Maven coordinates:

Artifact	Description
com.sphereon.kiwa:kiwa-holder-sdk-public	Public APIs, interfaces, and common code
com.sphereon.kiwa:kiwa-holder-sdk-impl	Implementation classes (includes public APIs)
com.sphereon.kiwa:kiwa-holder-sdk-all	Complete SDK with pre-built DI components (recommended)

Setting Up Authentication

Contact Sphereon to obtain your Nexus credentials for accessing the kiwa-releases and kiwa-snapshots repositories.

Maven Authentication

Add your credentials to ~/.m2/settings.xml:

<settings>
  <servers>
    <server>
      <id>kiwa-releases</id>
      <username>YOUR_NEXUS_USERNAME</username>
      <password>YOUR_NEXUS_PASSWORD</password>
    </server>
    <server>
      <id>kiwa-snapshots</id>
      <username>YOUR_NEXUS_USERNAME</username>
      <password>YOUR_NEXUS_PASSWORD</password>
    </server>
  </servers>
</settings>

Gradle Authentication

Add your credentials to ~/.gradle/gradle.properties:

nexusUsername=YOUR_NEXUS_USERNAME
nexusPassword=YOUR_NEXUS_PASSWORD

Android/JVM Configuration

Maven

Add the repositories and dependencies to your pom.xml:

<project>
  <repositories>
    <repository>
      <id>kiwa-releases</id>
      <url>https://nexus.sphereon.com/content/repositories/kiwa-releases/</url>
    </repository>
    <repository>
      <id>kiwa-snapshots</id>
      <url>https://nexus.sphereon.com/content/repositories/kiwa-snapshots/</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>

  <dependencies>
    <!-- Recommended: Complete SDK with DI components -->
    <dependency>
      <groupId>com.sphereon.kiwa</groupId>
      <artifactId>kiwa-holder-sdk-all</artifactId>
      <version>0.13.0</version>
    </dependency>
  </dependencies>
</project>

Gradle (Groovy DSL)

Add to your build.gradle:

repositories {
    maven {
        url 'https://nexus.sphereon.com/content/repositories/kiwa-releases/'
        credentials {
            username = project.findProperty('nexusUsername') ?: System.getenv('NEXUS_USERNAME')
            password = project.findProperty('nexusPassword') ?: System.getenv('NEXUS_PASSWORD')
        }
    }
    maven {
        url 'https://nexus.sphereon.com/content/repositories/kiwa-snapshots/'
        credentials {
            username = project.findProperty('nexusUsername') ?: System.getenv('NEXUS_USERNAME')
            password = project.findProperty('nexusPassword') ?: System.getenv('NEXUS_PASSWORD')
        }
    }
}

dependencies {
    // Recommended: Complete SDK with DI components
    implementation 'com.sphereon.kiwa:kiwa-holder-sdk-all:0.13.0'

    // Or use individual modules
    // implementation 'com.sphereon.kiwa:kiwa-holder-sdk-impl:0.13.0'
}

Gradle (Kotlin DSL)

Add to your build.gradle.kts:

repositories {
    maven {
        url = uri("https://nexus.sphereon.com/content/repositories/kiwa-releases/")
        credentials {
            username = project.findProperty("nexusUsername") as String?
                ?: System.getenv("NEXUS_USERNAME")
            password = project.findProperty("nexusPassword") as String?
                ?: System.getenv("NEXUS_PASSWORD")
        }
    }
    maven {
        url = uri("https://nexus.sphereon.com/content/repositories/kiwa-snapshots/")
        credentials {
            username = project.findProperty("nexusUsername") as String?
                ?: System.getenv("NEXUS_USERNAME")
            password = project.findProperty("nexusPassword") as String?
                ?: System.getenv("NEXUS_PASSWORD")
        }
    }
}

dependencies {
    // Recommended: Complete SDK with DI components
    implementation("com.sphereon.kiwa:kiwa-holder-sdk-all:0.13.0")

    // Or use individual modules
    // implementation("com.sphereon.kiwa:kiwa-holder-sdk-impl:0.13.0")
}

tip

For development builds, use 0.13.0-SNAPSHOT instead of 0.13.0. Ensure snapshots are enabled in your repository configuration.

Local Binary Installation

If you prefer to use local JAR files instead of the Nexus repository:

Obtaining Binaries

1. Contact Sphereon to receive the JAR files directly, or

2. Download from Nexus (if you have access):

   • https://nexus.sphereon.com/content/repositories/kiwa-releases/com/sphereon/kiwa/
   • https://nexus.sphereon.com/content/repositories/kiwa-snapshots/com/sphereon/kiwa/

3. Place the JAR files in a libs/ directory in your project

Maven Local Dependencies

<dependencies>
  <dependency>
    <groupId>com.sphereon.kiwa</groupId>
    <artifactId>kiwa-holder-sdk-all</artifactId>
    <version>0.13.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/kiwa-holder-sdk-all-0.13.0.jar</systemPath>
  </dependency>
</dependencies>

Gradle Local Dependencies

dependencies {
    implementation files('libs/kiwa-holder-sdk-all-0.13.0.jar')

    // Or include all JARs from a directory
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

Kotlin DSL:

dependencies {
    implementation(files("libs/kiwa-holder-sdk-all-0.13.0.jar"))

    // Or include all JARs from a directory
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
}

warning

When using local dependencies, ensure JAR files are documented and accessible to all team members.

iOS Installation

The Kiwa SDK is available for iOS as an XCFramework. You can integrate it using CocoaPods, direct XCFramework download, or build it yourself from source.

note

The iOS API closely mirrors the Android API. While not fully idiomatic Swift, this ensures consistency across platforms. The SDK uses SKIE for enhanced Swift interoperability.

Installation Options

Method	Best For	Complexity
CocoaPods	React Native projects, existing CocoaPods workflows	Low
Direct XCFramework	Simple Xcode projects, manual control	Low
Build from Source	Custom modifications, latest changes	High

CocoaPods Integration

CocoaPods is the recommended approach for React Native projects and teams already using CocoaPods.

1. Configure Authentication

Add your Nexus credentials to your environment:

export KIWA_REPO_USER="your-username"
export KIWA_REPO_PASSWORD="your-password"

Or add to your ~/.netrc file for persistent authentication:

machine nexus.sphereon.com
login your-username
password your-password

2. Add to Podfile

In your project's ios/Podfile:

# Option A: Reference the podspec from the repository
pod 'KiwaSdk', :podspec => 'https://raw.githubusercontent.com/Sphereon-Opensource/kiwa-sample/main/example/holder/xcframework/build/cocoapods/KiwaSdk.podspec'

# Option B: Reference a local podspec (for development)
pod 'KiwaSdk', :podspec => '/path/to/kiwa-sample/example/holder/xcframework/build/cocoapods/KiwaSdk.podspec'

# Option C: Use a private spec repo
source 'https://github.com/your-org/private-podspecs.git'
pod 'KiwaSdk', '~> 0.13.0'

3. Install Dependencies

cd ios
pod install

Direct XCFramework Integration

For projects not using CocoaPods, you can download and integrate the XCFramework directly.

1. Download from Nexus

# For release versions
curl -u "$KIWA_REPO_USER:$KIWA_REPO_PASSWORD" \
  -O "https://nexus.sphereon.com/repository/kiwa-releases/com/sphereon/kiwa/kiwa-sdk-ios/0.13.0/kiwa-sdk-ios-0.13.0.zip"

# For snapshots
curl -u "$KIWA_REPO_USER:$KIWA_REPO_PASSWORD" \
  -O "https://nexus.sphereon.com/repository/kiwa-snapshots/com/sphereon/kiwa/kiwa-sdk-ios/0.13.0-SNAPSHOT/kiwa-sdk-ios-0.13.0-SNAPSHOT.zip"

unzip kiwa-sdk-ios-*.zip

2. Add to Xcode Project

1. Open your Xcode project
2. Select your project in the Navigator
3. Select your target under "Targets"
4. Go to General > Frameworks, Libraries, and Embedded Content
5. Click + > Add Other... > Add Files...
6. Navigate to and select KiwaSdk.xcframework
7. Set Embed to Embed & Sign

Building the XCFramework

For development or customization, you can build the XCFramework from source. The build is located in a separate Gradle project to avoid slowing down the main build.

Building the XCFramework yourself allows you to customize which IDK (Identity Development Kit) components are included. By default, the framework includes:

• mDoc Data Transfer - BLE (Bluetooth Low Energy) and NFC engagement for presenting credentials to verifiers

If your application doesn't require proximity presentation features, you can exclude these modules to reduce the framework size and avoid unnecessary platform permission requirements.

warning

Building the XCFramework requires macOS with Xcode 15+ installed. The process is time-consuming as it compiles Kotlin/Native for multiple iOS architectures.

Prerequisites

• macOS with Xcode 15+ installed
• JDK 17 or higher
• Gradle 8.x (included via wrapper)
• Access to Kiwa Maven repositories

Build Commands

Navigate to the xcframework directory and run:

cd example/holder/xcframework

# Build XCFramework for all iOS targets (debug + release)
./gradlew assembleXCFrameworkKiwaSdk

# Build release only (faster)
./gradlew assembleReleaseXCFrameworkKiwaSdk

# Build debug only
./gradlew assembleDebugXCFrameworkKiwaSdk

Build Output

The generated XCFramework will be located at:

build/XCFrameworks/release/KiwaSdk.xcframework
build/XCFrameworks/debug/KiwaSdk.xcframework

The XCFramework includes support for:

• iosArm64 - Physical iOS devices (iPhone, iPad)
• iosX64 - iOS Simulator on Intel Macs
• iosSimulatorArm64 - iOS Simulator on Apple Silicon Macs

Publishing to Nexus

To publish the built XCFramework to Nexus (Sphereon internal):

./gradlew publishXcframeworkPublicationToNexusRepository

# Generate podspec for CocoaPods
./gradlew generatePodspec

Using in Swift

import KiwaSdk

// SDK is now available for use
// See the DI and Holder Functions guides for usage examples

tip

After updating the XCFramework, clean your Xcode project (Product > Clean Build Folder) to ensure the latest version is used.

Troubleshooting iOS Installation

Authentication Issues

If you encounter 401/403 errors:

1. Verify your Nexus credentials are correct
2. Check that you have read access to the repository
3. For CocoaPods, ensure credentials are in ~/.netrc

Framework Not Found

1. Run pod deintegrate && pod install to clean reinstall
2. Verify the XCFramework exists at the expected Nexus URL
3. Check your Podfile is referencing the correct version

Architecture Issues

The XCFramework includes all required architectures. If you see architecture errors:

1. Ensure you're building for a supported platform
2. Check that "Embed & Sign" is selected in build settings
3. Verify Xcode is using the correct SDK version

Build Failures (from source)

• "No KIWA_REPO_USER environment...": Configure repository credentials
• Non-macOS build: XCFramework compilation requires macOS with Xcode
• Out of memory: Increase Gradle JVM memory in gradle.properties:

  org.gradle.jvmargs=-Xmx8092M

Platform Requirements

Platform	Minimum Version	Notes
Android	API 27 (Android 8.1)	Full support
iOS	arm64, x64, simulator-arm64	XCFramework required
JVM	Java 17	For desktop/server use

Next Steps

After installation, proceed to:

1. Dependency Injection - Initialize the SDK components
2. Holder Functions - Implement license operations