Implementing eSIM Management in Mobile App
eSIM Management in mobile app is not just showing a list of profiles. It's working with device's Local Profile Agent (LPA) via GSMA SGP.22 standard, balancing between SM-DP+ operator server and iOS/Android limitations on eUICC access, and handling multi-level activation errors that platform usually hides behind cryptic "Connection error".
Standards and Platform Limitations
GSMA SGP.22 (Consumer Profile) for consumer devices. SGP.32 (IoT) for M2M modules. Mobile apps work with SGP.22.
iOS limitations are serious. Apple doesn't provide public API for programmatic eSIM profile management. Only:
-
CoreTelephony.CTCarrier— active carrier info (no profile management) - QR activation via
com.apple.esimURL scheme — opens system UI - Carrier App entitlement — only operators with Apple agreement
For carrier-grade app (operator app): com.apple.developer.networking.multipath + special Apple entitlement, available only through Mobile Network Operator Program.
Android is significantly more open. EuiccManager API (Android 9+) available for operators via android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS. For regular apps — unavailable. But devices with LPA in Application implementation allow apps to interact with LPA via Intent-based API.
Android EuiccManager: Operator Path
val euiccManager = getSystemService(Context.EUICC_SERVICE) as EuiccManager
if (!euiccManager.isEnabled) {
showError("eSIM not supported on this device")
return
}
// Load profile by activation code
val switchIntent = Intent("android.telephony.euicc.action.START_EUICC_ACTIVATION")
switchIntent.putExtra("activation_code", "LPA:1\$smdp.example.com\$ACTIVATION_CODE")
startActivityForResult(switchIntent, REQUEST_CODE_ESIM_DOWNLOAD)
Direct access via downloadSubscription() — only with WRITE_EMBEDDED_SUBSCRIPTIONS, which is signature-bound to operator or given via Device Policy Controller:
// Only for carrier-privileged apps
val result = euiccManager.downloadSubscription(
DownloadableSubscription.forActivationCode("LPA:1\$smdp.example.com\$CODE"),
switchAfterDownload = true,
cancelSignal = cancellationSignal,
executor = mainExecutor
) { resultCode, extras ->
when (resultCode) {
EuiccManager.EMBEDDED_SUBSCRIPTION_RESULT_OK -> onSuccess()
EuiccManager.EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR -> {
// Requires user action — show system dialog
euiccManager.startResolutionActivity(activity, extras, pendingIntent)
}
EuiccManager.EMBEDDED_SUBSCRIPTION_RESULT_ERROR -> {
val detailedCode = extras?.getInt(EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE)
handleError(detailedCode)
}
}
}
EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR is the most important code. Means platform knows how to solve problem (user confirmation, authentication) but needs system UI. Don't bypass — show startResolutionActivity.
SM-DP+ Server Side
Mobile app is thin client. Main logic on SM-DP+ (Subscription Management Data Preparation+) operator server. Stores profiles, generates activation codes, manages lifecycle:
App → Backend API → SM-DP+ Server → eUICC (via LPA on device)
Activation Code format (SGP.22): LPA:1$<SM-DP+ FQDN>$<Matching ID>[$<OID>[$<Confirmation Code Required>]]
Backend generates unique Matching ID for each activation — one-time token bound to specific ICCID. After use, becomes invalid.
Profile Info Without Privileges
For apps without carrier privileges — read what's available:
// List SIM cards (including eSIM profiles)
val subscriptionManager = getSystemService(Context.TELEPHONY_SUBSCRIPTION_SERVICE) as SubscriptionManager
val activeSubscriptions = subscriptionManager.activeSubscriptionInfoList
activeSubscriptions?.forEach { sub ->
Log.d("eSIM", "Carrier: ${sub.carrierName}, SIM slot: ${sub.simSlotIndex}, eSIM: ${sub.isEmbedded}")
}
isEmbedded = true means profile on eUICC. Switching between active profiles without privileges is impossible on Android. On iOS completely unavailable programmatically.
Timeline
App showing eSIM status and activation via QR/activation code (Intent-based, no system privileges): 2–4 weeks. Full carrier app with WRITE_EMBEDDED_SUBSCRIPTIONS and SM-DP+ API integration: 1–3 months. Timeline heavily depends on operator access and SM-DP+ environment availability.