Android SDK: Initialize

Initialize the Android Digital Card Engine UI SDK and the underlying Ei Card Provider core SDK. Call initialize() early (for example, in Application.onCreate) once you have a short‑lived auth token from your backend.

Prerequisites:

• Repositories and dependencies configured (see Setup page)
• DCE configuration parameters from your backend (do not hardcode secrets)

What initialize() does

• Configures the core SDK with your DCE credentials and selected environment
• Initializes MeaWallet's MCD library for secure card image rendering
• Sets up authentication via signature-based DceConfiguration
• Leaves style/theming mutable via sdk.styleConfiguration for customization

Basic initialization

import android.app.Application
import com.paymentology.digital_card_engine_sdk_android.DigitalCardEngineSDK
import com.paymentology.ei_card_provider_sdk.DceConfiguration
import com.paymentology.ei_card_provider_sdk.Environment

class MyApp : Application() {
    lateinit var sdk: DigitalCardEngineSDK

    override fun onCreate() {
        super.onCreate()

        sdk = DigitalCardEngineSDK()
        
        // Configure with your DCE API credentials
        val config = DceConfiguration(
            clientId = "your-client-id",
            accountId = "your-account-id",
            userId = "your-user-id",
            apiKeyId = "your-api-key-id",
            aesKey = "your-aes-key"
        )
        
        sdk.initialize(
            context = applicationContext,
            env = Environment.TEST,  // DEV | TEST | PROD
            dceConfiguration = config,
            totpCallback = { challenge ->
                // Optional: Return TOTP code for MCD authentication
                generateTotpCode(challenge)
            }
        )
    }
}

Parameters

DceConfiguration

Provide API credentials for signature-based authentication:

data class DceConfiguration(
    val clientId: String,      // Client identifier
    val accountId: String,     // Account identifier
    val userId: String,        // User identifier
    val apiKeyId: String,      // API key ID
    val aesKey: String         // AES encryption key
)

Important: Fetch these values securely from your backend at runtime. Never hardcode credentials in your app.

Guidelines

• One instance: Keep a single shared DigitalCardEngineSDK instance (application singleton or DI) and reuse across screens
• Initialize once: Call initialize() once per app process start, typically in Application.onCreate()
• Secure credentials: Fetch DCE configuration from your backend, never hardcode
• Customize after init: Modify sdk.styleConfiguration after initialization but before rendering UI

Environments

Use Environment.DEV, Environment.TEST, or Environment.PROD. Default for initialize() is TEST. The core SDK resolves base URLs from the card_provider_sdk build config:

• DEV → https://ei.dev.meawallet.app
• TEST → https://ei.tst.meawallet.app
• PROD → https://ei.prd.meawallet.app

Token refresh

When your backend issues a new token, update the already-initialized core SDK—no need to recreate DigitalCardEngineSDK:

import com.paymentology.ei_card_provider_sdk.EiCardProviderSDK

// Called whenever you obtain a fresh token
fun refreshToken(newToken: String) {
  EiCardProviderSDK.updateAuthToken(newToken)
}

Troubleshooting

• "Auth token cannot be empty or blank": ensure you supply a runtime token string.
• "Auth token appears to be too short": token validation failed; fetch a real token from your backend.
• MCD errors during card image rendering usually indicate missing TOTP secret, missing card selection, or MCD artifact/config issues.

Next steps: continue to the setup/install page to add repos + dependencies, then use the Card List / Card Details pages to render UI.