EuiccManager

public class EuiccManager
extends Object

java.lang.Object
   ↳ android.telephony.euicc.EuiccManager


EuiccManager is the application interface to eUICCs, or eSIMs/embedded SIMs.

You do not instantiate this class directly; instead, you retrieve an instance through getSystemService(String) and EUICC_SERVICE.

See isEnabled() before attempting to use these APIs.

Summary

Constants

String ACTION_MANAGE_EMBEDDED_SUBSCRIPTIONS

Intent action to launch the embedded SIM (eUICC) management settings screen.

String ACTION_NOTIFY_CARRIER_SETUP_INCOMPLETE

Broadcast Action: The action sent to carrier app so it knows the carrier setup is not completed.

int EMBEDDED_SUBSCRIPTION_RESULT_ERROR

Result code for an operation indicating that an unresolvable error occurred.

int EMBEDDED_SUBSCRIPTION_RESULT_OK

Result code for an operation indicating that the operation succeeded.

int EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR

Result code for an operation indicating that the user must take some action before the operation can continue.

String EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE

Key for an extra set on PendingIntent result callbacks providing a detailed result code.

String EXTRA_EMBEDDED_SUBSCRIPTION_DOWNLOADABLE_SUBSCRIPTION

Key for an extra set on #getDownloadableSubscriptionMetadata PendingIntent result callbacks providing the downloadable subscription metadata.

String META_DATA_CARRIER_ICON

Optional meta-data attribute for a carrier app providing an icon to use to represent the carrier.

Public methods

void deleteSubscription(int subscriptionId, PendingIntent callbackIntent)

Deletes the given subscription.

void downloadSubscription(DownloadableSubscription subscription, boolean switchAfterDownload, PendingIntent callbackIntent)

Attempt to download the given DownloadableSubscription.

String getEid()

Returns the EID identifying the eUICC hardware.

EuiccInfo getEuiccInfo()

Returns information about the eUICC chip/device.

boolean isEnabled()

Whether embedded subscriptions are currently enabled.

void startResolutionActivity(Activity activity, int requestCode, Intent resultIntent, PendingIntent callbackIntent)

Start an activity to resolve a user-resolvable error.

void switchToSubscription(int subscriptionId, PendingIntent callbackIntent)

Switch to (enable) the given subscription.

Inherited methods

Constants

ACTION_MANAGE_EMBEDDED_SUBSCRIPTIONS

String ACTION_MANAGE_EMBEDDED_SUBSCRIPTIONS

Intent action to launch the embedded SIM (eUICC) management settings screen.

This screen shows a list of embedded profiles and offers the user the ability to switch between them, download new profiles, and delete unused profiles.

The activity will immediately finish with RESULT_CANCELED if isEnabled() is false. This is ued by non-LPA app to bring up LUI.

Constant Value: "android.telephony.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS"

ACTION_NOTIFY_CARRIER_SETUP_INCOMPLETE

String ACTION_NOTIFY_CARRIER_SETUP_INCOMPLETE

Broadcast Action: The action sent to carrier app so it knows the carrier setup is not completed.

Constant Value: "android.telephony.euicc.action.NOTIFY_CARRIER_SETUP_INCOMPLETE"

EMBEDDED_SUBSCRIPTION_RESULT_ERROR

int EMBEDDED_SUBSCRIPTION_RESULT_ERROR

Result code for an operation indicating that an unresolvable error occurred. EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE will be populated with a detailed error code for logging/debugging purposes only.

Constant Value: 2 (0x00000002)

EMBEDDED_SUBSCRIPTION_RESULT_OK

int EMBEDDED_SUBSCRIPTION_RESULT_OK

Result code for an operation indicating that the operation succeeded.

Constant Value: 0 (0x00000000)

EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR

int EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR

Result code for an operation indicating that the user must take some action before the operation can continue.

Constant Value: 1 (0x00000001)

EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE

String EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE

Key for an extra set on PendingIntent result callbacks providing a detailed result code.

This code is an implementation detail of the embedded subscription manager and is only intended for logging or debugging purposes.

Constant Value: "android.telephony.euicc.extra.EMBEDDED_SUBSCRIPTION_DETAILED_CODE"

EXTRA_EMBEDDED_SUBSCRIPTION_DOWNLOADABLE_SUBSCRIPTION

String EXTRA_EMBEDDED_SUBSCRIPTION_DOWNLOADABLE_SUBSCRIPTION

Key for an extra set on #getDownloadableSubscriptionMetadata PendingIntent result callbacks providing the downloadable subscription metadata.

Constant Value: "android.telephony.euicc.extra.EMBEDDED_SUBSCRIPTION_DOWNLOADABLE_SUBSCRIPTION"

META_DATA_CARRIER_ICON

String META_DATA_CARRIER_ICON

Optional meta-data attribute for a carrier app providing an icon to use to represent the carrier. If not provided, the app's launcher icon will be used as a fallback.

Constant Value: "android.telephony.euicc.carriericon"

Public methods

deleteSubscription

void deleteSubscription (int subscriptionId, 
                PendingIntent callbackIntent)

Deletes the given subscription.

If this subscription is currently active, the device will first switch away from it onto an "empty" subscription.

Requires that the calling app has carrier privileges according to the metadata of the profile to be deleted, or the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission.

Requires the permission.

Parameters
subscriptionId int: the ID of the subscription to delete.

callbackIntent PendingIntent: a PendingIntent to launch when the operation completes.

downloadSubscription

void downloadSubscription (DownloadableSubscription subscription, 
                boolean switchAfterDownload, 
                PendingIntent callbackIntent)

Attempt to download the given DownloadableSubscription.

Requires the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission, or the calling app must be authorized to manage both the currently-active subscription and the subscription to be downloaded according to the subscription metadata. Without the former, an EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR will be returned in the callback intent to prompt the user to accept the download.

Requires the permission.

Parameters
subscription DownloadableSubscription: the subscription to download.

switchAfterDownload boolean: if true, the profile will be activated upon successful download.

callbackIntent PendingIntent: a PendingIntent to launch when the operation completes.

getEid

String getEid ()

Returns the EID identifying the eUICC hardware.

Requires that the calling app has carrier privileges on the active subscription on the eUICC.

Returns
String the EID. May be null if isEnabled() is false or the eUICC is not ready.

getEuiccInfo

EuiccInfo getEuiccInfo ()

Returns information about the eUICC chip/device.

Returns
EuiccInfo the EuiccInfo. May be null if isEnabled() is false or the eUICC is not ready.

isEnabled

boolean isEnabled ()

Whether embedded subscriptions are currently enabled.

Even on devices with the FEATURE_TELEPHONY_EUICC feature, embedded subscriptions may be turned off, e.g. because of a carrier restriction from an inserted physical SIM. Therefore, this runtime check should be used before accessing embedded subscription APIs.

Returns
boolean true if embedded subscriptions are currently enabled.

startResolutionActivity

void startResolutionActivity (Activity activity, 
                int requestCode, 
                Intent resultIntent, 
                PendingIntent callbackIntent)

Start an activity to resolve a user-resolvable error.

If an operation returns EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR, this method may be called to prompt the user to resolve the issue.

This method may only be called once for a particular error.

Parameters
activity Activity: the calling activity (which should be in the foreground).

requestCode int: an application-specific request code which will be provided to onActivityResult(int, int, Intent) upon completion. Note that the operation may still be in progress when the resolution activity completes; it is not fully finished until the callback intent is triggered.

resultIntent Intent: the Intent provided to the initial callback intent which failed with EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR.

callbackIntent PendingIntent: a PendingIntent to launch when the operation completes. This is trigered upon completion of the original operation that required user resolution.

Throws
IntentSender.SendIntentException if called more than once.

switchToSubscription

void switchToSubscription (int subscriptionId, 
                PendingIntent callbackIntent)

Switch to (enable) the given subscription.

Requires the android.Manifest.permission#WRITE_EMBEDDED_SUBSCRIPTIONS permission, or the calling app must be authorized to manage both the currently-active subscription and the subscription to be enabled according to the subscription metadata. Without the former, an EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR will be returned in the callback intent to prompt the user to accept the download.

Requires the permission.

Parameters
subscriptionId int: the ID of the subscription to enable. May be INVALID_SUBSCRIPTION_ID to deactivate the current profile without activating another profile to replace it.

callbackIntent PendingIntent: a PendingIntent to launch when the operation completes.