Skip to main content
Version: v0.13

Application Setup

This guide walks through the complete setup of an IDK-integrated application, from creating the application component to accessing services within a session.

Application Component Initialization​

The application component is the root of your IDK integration. It must be initialized before any other IDK operations can be performed.

import com.sphereon.idk.core.di.IdkAppComponent

class MyApplication : Application() {
    lateinit var idkApp: IdkAppComponent
        private set

    override fun onCreate() {
        super.onCreate()

        idkApp = IdkAppComponent.init(
            application = this,
            appId = "com.example.myapp",
            profile = BuildConfig.BUILD_TYPE,  // "debug" or "release"
            version = BuildConfig.VERSION_NAME
        )
    }
}

Register your Application class in AndroidManifest.xml:

<application
    android:name=".MyApplication"
    ...>
</application>

Initialization Parameters​

The initialization parameters serve specific purposes:

ParameterPurpose
applicationThe platform application instance (Android Context or iOS UIApplication)
appIdIdentifier used in configuration property resolution and logging
profileEnvironment profile for selecting configuration (e.g., "debug", "production")
versionYour application version, used for logging and diagnostics

Setting Up User Context​

After creating the application component, establish a user context. The user context represents a tenant and principal, enabling multi-tenant isolation.

Multi-Tenant Setup​

For applications that serve multiple organizations or users:

// Get the user context manager from the app component
val userContextManager = idkApp.userContextManager

// Create a user context for a specific tenant and user
val userContext = userContextManager.createOrGetFromInputs(
    tenantInput = DefaultTenantInputString(tenant = "acme-corp"),
    principalInput = DefaultPrincipalInputString(principal = "alice@acme-corp.com"),
    makeActive = true
)

Single-Tenant Setup​

For applications that don't need multi-tenancy, use the anonymous context:

val userContext = idkApp.userContextManager.getAnonymous(makeActive = true)

The anonymous context provides a default tenant and principal, simplifying the code while maintaining the same scope structure.

Creating Sessions​

Sessions are where most work happens. A session represents an active working context with access to services.

// Create a session with a unique identifier
val sessionContextManager = userContext.sessionContextManager
val session = sessionContextManager.createOrGetFromId(
    sessionId = "main-session",
    makeActive = true
)

// Access the session component for services
val sessionComponent = session.component

Session Lifecycle Strategies​

Different applications have different session lifecycle needs:

For mobile wallet applications, you might create a long-lived session at user login and destroy it at logout:

// On login
fun onUserLogin(userId: String) {
    val userContext = idkApp.userContextManager.createOrGetFromInputs(
        tenantInput = DefaultTenantInputString(tenant = "default"),
        principalInput = DefaultPrincipalInputString(principal = userId),
        makeActive = true
    )
    session = userContext.sessionContextManager.createOrGetFromId(
        sessionId = "user-session",
        makeActive = true
    )
}

// On logout
fun onUserLogout() {
    session?.let {
        it.contextManager.destroy(sessionId = "user-session")
    }
    session = null
}

For credential presentation flows, you might create a short-lived session for each presentation:

suspend fun presentCredential() {
    val session = userContext.sessionContextManager.createOrGetFromId(
        sessionId = UUID.randomUUID().toString(),
        makeActive = true
    )

    try {
        val engagementManager = session.component.engagementManager
        // Perform presentation...
    } finally {
        userContext.sessionContextManager.destroy(sessionId = session.sessionId)
    }
}

Accessing Services​

Services are accessed through the session component. The component provides type-safe access to all IDK services.

val sessionComponent = session.component

// Key management
val keyManager = sessionComponent.keyManagerService

// mDoc engagement
val engagementManager = sessionComponent.engagementManager

// OAuth 2.0 client
val oauth2Client = sessionComponent.oauth2Client

// Configuration
val configProvider = sessionComponent.configProvider

// Logging
val logger = sessionComponent.logger

Complete Setup Example​

Here's a complete example combining all the setup steps:

class MyApplication : Application() {
    lateinit var idkApp: IdkAppComponent
        private set

    override fun onCreate() {
        super.onCreate()
        idkApp = IdkAppComponent.init(
            application = this,
            appId = "com.example.wallet",
            profile = BuildConfig.BUILD_TYPE,
            version = BuildConfig.VERSION_NAME
        )
    }
}

class MainActivity : ComponentActivity() {
    private var session: SessionContextInstance? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Get the IDK app component
        val idkApp = (application as MyApplication).idkApp

        // Create user context (anonymous for this example)
        val userContext = idkApp.userContextManager.getAnonymous(makeActive = true)

        // Create a session
        session = userContext.sessionContextManager.createOrGetFromId(
            sessionId = "main-session",
            makeActive = true
        )

        // Now you can use IDK services
        val keyManager = session!!.component.keyManagerService
        val engagementManager = session!!.component.engagementManager

        // Continue with your app logic...
    }

    override fun onDestroy() {
        super.onDestroy()
        // Clean up session if needed
        session?.contextManager?.destroy(sessionId = "main-session")
    }
}

Next Steps​

With your application set up, you can now:

  1. Configure multi-tenancy if your application serves multiple organizations
  2. Set up configuration properties for customizing behavior
  3. Start using IDK services like key management or mDoc presentation