# Android Initialize

# 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](setup.md) 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

```kotlin
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

| Parameter          | Type               | Required | Default | Description                                      |
| ------------------ | ------------------ | -------- | ------- | ------------------------------------------------ |
| `context`          | `Context`          | Yes      | -       | Android application context                      |
| `env`              | `Environment`      | No       | `TEST`  | Environment (DEV, TEST, PROD)                    |
| `dceConfiguration` | `DceConfiguration` | Yes      | -       | API credentials for signature-based auth         |
| `totpCallback`     | `TotpCallback?`    | No       | `null`  | Callback for TOTP generation (MCD secure fields) |

## DceConfiguration

Provide API credentials for signature-based authentication:

```kotlin
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`:

```kotlin
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.