API eUICC

Dans Android 9, les API de gestion des profils (publiques et @SystemApi) sont disponibles via la classe EuiccManager. Les API de communication eUICC (@SystemApi uniquement) sont disponibles via la classe EuiccCardManager.

À propos de l'eUICC

Les opérateurs peuvent créer des applications d'opérateur à l'aide d'EuiccManager pour gérer les profils, comme illustré à la figure 1. Les applications d'opérateur n'ont pas besoin d'être des applications système, mais doivent disposer des droits d'opérateur accordés par les profils eUICC. Une application LPA (UI LPA et backend LPA) doit être une application système (c'est-à-dire incluse dans l'image système) pour appeler @SystemApi.

Téléphone Android avec application de l'opérateur et LPA OEM

Figure 1 : Téléphones Android avec application de l'opérateur et LPA OEM

En plus de la logique d'appel de EuiccCardManager et de communication avec l'eUICC, les applications LPA doivent implémenter les éléments suivants :

  • Client SM-DP+ communiquant avec le serveur SM-DP+ pour authentifier et télécharger des profils
  • [Facultatif] SM-DS pour obtenir plus de profils téléchargeables potentiels
  • Gestion des notifications pour envoyer des notifications au serveur afin de mettre à jour l'état du profil
  • [Facultatif] Gestion des emplacements, y compris le basculement entre la logique eSIM et pSIM. Cette étape est facultative si le téléphone ne dispose que d'une puce eSIM.
  • eSIM OTA

Bien qu'un téléphone Android puisse contenir plusieurs applications LPA, une seule peut être sélectionnée comme LPA fonctionnel en fonction de la priorité définie dans le fichier AndroidManifest.xml de chaque application.

Utiliser EuiccManager

Les API LPA sont publiques via EuiccManager (sous le package android.telephony.euicc). Une application d'opérateur peut obtenir l'instance de EuiccManager et appeler les méthodes dans EuiccManager pour obtenir les informations eUICC et gérer les abonnements (appelés profils dans les documents GSMA RSP) en tant qu'instances SubscriptionInfo.

Pour appeler des API publiques, y compris les opérations de téléchargement, de changement et de suppression d'abonnement, l'application de l'opérateur doit disposer des droits requis. Les droits d'accès de l'opérateur sont ajoutés par l'opérateur mobile dans les métadonnées du profil. L'API eUICC applique les règles de privilèges de l'opérateur en conséquence.

La plate-forme Android ne gère pas les règles relatives aux profils. Si une règle de stratégie est déclarée dans les métadonnées du profil, le LPA peut choisir comment gérer la procédure de téléchargement et d'installation du profil. Par exemple, il est possible qu'un LPA OEM tiers gère les règles de stratégie à l'aide d'un code d'erreur spécial (le code d'erreur est transmis du LPA OEM à la plate-forme, puis la plate-forme transmet le code à l'IUI OEM).

Pour en savoir plus sur les API de plusieurs profils activés, consultez Plusieurs profils activés.

API

Les API suivantes sont disponibles dans la documentation de référence EuiccManager et EuiccManager.java.

Obtenir l'instance (publique)

Obtient l'instance de EuiccManager via Context#getSystemService. Pour en savoir plus, consultez getSystemService.

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

Vérification activée (publique)

Vérifie si l'abonnement intégré est activé. Cette vérification doit être effectuée avant d'accéder aux API LPA. Pour plus d'informations, consultez isEnabled.

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

Obtenir l'EID (public)

Obtient l'EID identifiant le matériel eUICC. Cette valeur peut être nulle si l'eUICC n'est pas prêt. L'appelant doit disposer du droit d'accès à l'opérateur ou de l'autorisation READ_PRIVILEGED_PHONE_STATE. Pour en savoir plus, consultez getEid.

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

Get EuiccInfo (public)

Obtient des informations sur l'eUICC. Il contient la version de l'OS. Pour en savoir plus, consultez getEuiccInfo.

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

Télécharger un abonnement (public)

Télécharge l'abonnement donné (appelé "profil" dans les documents GSMA RSP). L'abonnement peut être créé à partir d'un code d'activation. Par exemple, un code d'activation peut être analysé à partir d'un code QR. Le téléchargement d'un abonnement est une opération asynchrone.

L'appelant doit disposer de l'autorisation WRITE_EMBEDDED_SUBSCRIPTIONS ou des droits d'opérateur pour l'abonnement cible. Pour en savoir plus, consultez 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);

Changer d'abonnement (public)

Passe à l'abonnement indiqué (l'active). L'appelant doit disposer de l'autorisation WRITE_EMBEDDED_SUBSCRIPTIONS ou des droits de l'opérateur pour l'abonnement activé actuel et l'abonnement cible. Pour en savoir plus, consultez 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);

Changer d'abonnement avec portage (public)

(Disponible à partir d'Android 13) Passe à l'abonnement donné avec l'index de port spécifié (l'active). L'appelant doit disposer de l'autorisation WRITE_EMBEDDED_SUBSCRIPTIONS ou de privilèges d'opérateur pour l'abonnement activé actuel et l'abonnement cible. Pour en savoir plus, consultez 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);

Le port SIM est-il disponible (public) ?

public boolean isSimPortAvailable(int portIndex)

(Disponible à partir d'Android 13) Indique si l'index du port de transmission est disponible. Un port est disponible s'il n'est associé à aucun abonnement ou si l'application d'appel dispose de droits d'opérateur sur l'abonnement installé sur le port sélectionné. Pour plus d'informations, consultez isSimPortAvailable.

Supprimer un abonnement (public)

Supprime un abonnement avec un ID d'abonnement. Si l'abonnement est actuellement actif, il est d'abord désactivé. L'appelant doit disposer des droits WRITE_EMBEDDED_SUBSCRIPTIONS ou des droits de l'opérateur pour l'abonnement cible. Pour en savoir plus, consultez 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);

Effacer tous les abonnements (API système)

Efface tous les abonnements sur un appareil. À partir d'Android 11, vous devez fournir une valeur d'énumération EuiccCardManager#ResetOption pour spécifier s'il faut effacer tous les abonnements de test, opérationnels ou les deux types. L'appelant doit disposer de l'autorisation 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);

Démarrer une activité de résolution (publique)

Démarre une activité pour résoudre une erreur que l'utilisateur peut résoudre. Si une opération renvoie EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR, cette méthode peut être appelée pour inviter l'utilisateur à résoudre le problème. Cette méthode ne peut être appelée qu'une seule fois pour une erreur spécifique.

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

Constantes

Pour afficher la liste des constantes public dans EuiccManager, consultez Constantes.