APIs de eUICC

En Android 9, las APIs de administración de perfiles (públicas y @SystemApi) están disponibles a través de la clase EuiccManager. Comunicación eUICC Las APIs (solo @SystemApi) están disponibles a través de la clase EuiccCardManager.

Información acerca de eUICC

Los operadores pueden crear apps del operador usando EuiccManager para administrar perfiles, como se muestra. en la Figura 1. No es necesario que las apps del operador sean apps del sistema, pero sí deben tenerlas. privilegios que otorgan los perfiles eUICC. Los Aplicación de LPA (LUI y LPA) backend) debe ser una aplicación del sistema (es decir, incluida en la imagen del sistema) para llamar la @SystemApi.

Teléfono Android con app del operador y LPA del OEM

Figura 1: Teléfonos Android con app del operador y LPA del OEM

Además de la lógica de llamar a EuiccCardManager y hablar con eUICC, las apps de LPA debe implementar lo siguiente:

  • un cliente SM-DP+ que se comunica con un servidor SM-DP+ para autenticarse y descargar perfiles
  • [Opcional] SM-DS para obtener más posibles perfiles descargables
  • Manejo de notificaciones para enviar notificaciones al servidor a actualizar el estado del perfil
  • [Opcional] Administración de ranuras, incluido el cambio entre la lógica de eSIM y pSIM. Esto es opcional si el teléfono solo tiene un chip eSIM.
  • eSIM inalámbrica

Si bien un teléfono Android puede incluir más de una app de LPA, solo un LPA se puede seleccionar como el LPA que funciona realmente según la prioridad definida en el archivo AndroidManifest.xml de cada app

Cómo usar EuiccManager

Las APIs de LPA son públicas a través de EuiccManager (en el paquete android.telephony.euicc). Una app de operador puede obtener la instancia de EuiccManager. y llama a los métodos en EuiccManager para obtener la información eUICC y administrar (denominados perfiles en los documentos del RSP de GSMA) como SubscriptionInfo.

Para llamar a APIs públicas, lo que incluye descargar, cambiar y borrar suscripciones operaciones, la app del operador debe tener los privilegios necesarios. Proveedor El operador de telefonía celular agrega privilegios en los metadatos del perfil. El eUICC La API aplica las reglas de privilegios de operador en consecuencia.

La plataforma de Android no controla las reglas de la política de perfil. Si una regla de política en los metadatos del perfil, el LPA puede elegir cómo manejar el procedimiento de instalación y descarga de perfiles. Por ejemplo, es posible que un LPA de OEM de terceros para manejar las reglas de políticas con un código especial de error se pasa el código fuente del LPA del OEM a la plataforma y, luego, la plataforma pasa código en el LUI del OEM).

Para obtener información sobre varias APIs de perfiles habilitados, consulta Varios perfiles habilitados.

APIs

Puedes encontrar las siguientes APIs en el Documentación de referencia de EuiccManager y EuiccManager.java

Obtener instancia (pública)

Obtiene la instancia de EuiccManager a través de Context#getSystemService. Para obtener más información, consulta getSystemService

EuiccManager mgr = (EuiccManager) context.getSystemService(Context.EUICC_SERVICE);

Verificación habilitada (pública)

Comprueba si la suscripción incorporada está habilitada. Esto se debe verificar antes de acceder a las APIs de LPA. Para obtener más información, consulta isEnabled.

boolean isEnabled = mgr.isEnabled();
if (!isEnabled) {
    return;
}

Obtener EID (público)

Obtiene el EID que identifica el hardware eUICC. Puede ser nulo si el eUICC se que aún no está listo. El emisor debe tener privilegios de operador READ_PRIVILEGED_PHONE_STATE. Para obtener más información, consulta getEid

String eid = mgr.getEid();
if (eid == null) {
  // Handle null case.
}

Obtener EuiccInfo (público)

Obtiene información sobre el eUICC. Contiene la versión del SO. Para obtener más información, ver getEuiccInfo

EuiccInfo info = mgr.getEuiccInfo();
String osVer = info.getOsVersion();

Descargar suscripción (pública)

Descarga la suscripción en cuestión (denominado "perfil" en el RSP de GSMA) documentos). La suscripción se puede crear a partir de un código de activación. Para ejemplo, se puede analizar un código de activación a partir de un código QR. Descargar un suscripción es una operación asíncrona.

El llamador debe tener el permiso WRITE_EMBEDDED_SUBSCRIPTIONS tener privilegios de operador para la suscripción de destino. Para obtener más información, consulta downloadSubscription

// Register receiver.
String action = "download_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
                    0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(
        receiver,
        new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/, null /* handler */);

// Download subscription asynchronously.
DownloadableSubscription sub =
        DownloadableSubscription.forActivationCode(code /* encodedActivationCode*/);
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.downloadSubscription(sub, true /* switchAfterDownload */, callbackIntent);

Cambiar de suscripción (pública)

Cambia a (habilita) la suscripción determinada. El emisor debe tener WRITE_EMBEDDED_SUBSCRIPTIONS o si tienes privilegios de operador durante el período la suscripción habilitada y la suscripción de destino. Para obtener más información, consulta switchToSubscription

// Register receiver.
String action = "switch_to_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, 0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver, new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/, null /* handler */);

// Switch to a subscription asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.switchToSubscription(1 /* subscriptionId */, callbackIntent);

Cambiar de suscripción con puerto (público)

(Disponible a partir de Android 13) Cambia a (habilita) la suscripción determinada con el índice de puerto especificado. El emisor debe tener WRITE_EMBEDDED_SUBSCRIPTIONS o un operador para la suscripción habilitada actual y la suscripción de destino. Para obtener más información, consulta switchToSubscription

// Register receiver.
String action = "switch_to_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, 0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver, new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/, null /* handler */);

// Switch to a subscription asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.switchToSubscription(1 /* subscriptionId */, 0 /*portIndex*/, callbackIntent);

¿Hay un puerto SIM disponible (público)?

public boolean isSimPortAvailable(int portIndex)

(Disponible a partir de Android 13) Devuelve si el el índice de puerto que pasa. Un puerto está disponible si no tiene una suscripción habilitada o la aplicación que realiza la llamada tiene privilegios de operador sobre el suscripción instalada en el puerto seleccionado. Para obtener más información, consulta isSimPortAvailable.

Borrar suscripción (pública)

Borra una suscripción con un ID de suscripción. Si actualmente la suscripción está activo, primero se inhabilita. El emisor debe tener una de las siguientes opciones Privilegios de WRITE_EMBEDDED_SUBSCRIPTIONS o del proveedor para el destino suscripción. Para obtener más información, consulta deleteSubscription

// Register receiver.
String action = "delete_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
                    0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver, new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/,
        null /* handler */);

// Delete a subscription asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.deleteSubscription(1 /* subscriptionId */, callbackIntent);

Borrar todas las suscripciones (API del sistema)

Borra todas las suscripciones de un dispositivo. Primeros pasos en Android 11, debes proporcionar un EuiccCardManager#ResetOption enum para especificar si se deben borrar todas las pruebas, las operaciones o ambos suscripciones. El llamador debe tener el permiso WRITE_EMBEDDED_SUBSCRIPTIONS.

// Register receiver.
String action = "delete_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
                    0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver, new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/,
        null /* handler */);

// Erase all operational subscriptions asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.eraseSubscriptions(
        EuiccCardManager.RESET_OPTION_DELETE_OPERATIONAL_PROFILES, callbackIntent);

Iniciar actividad de resolución (pública)

Inicia una actividad para resolver un error que el usuario puede resolver. Si una operación devuelve EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR, este método puede ser para pedirle al usuario que resuelva el problema. Solo se puede llamar a este método una vez para un error en particular.

...
mgr.startResolutionActivity(getActivity(), 0 /* requestCode */, resultIntent, callbackIntent);

Constantes

Para ver una lista de las constantes public en EuiccManager, consulta la sección Constantes.