API eUICC

Sous Android 9, les API de gestion de profil (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érateurs à l'aide d'EuiccManager pour gérer les profils, comme illustré dans la figure 1. Les applications de l'opérateur ne doivent pas nécessairement être des applications système, mais elles doivent disposer des droits d'opérateur accordés par les profils eUICC. Une application LPA (UI 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 l'application de l'opérateur et la LPA de l'OEM

Figure 1 : Téléphones Android avec l'application de l'opérateur et la LPA de l'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 la logique pSIM. Cette étape est facultative si le téléphone ne dispose que d'une puce eSIM.
  • OTA eSIM

Bien que plusieurs applications LPA puissent être présentes dans un téléphone Android, un seul LPA peut être sélectionné comme LPA fonctionnel réel 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 de l'opérateur peut obtenir l'instance de EuiccManager et appeler les méthodes de 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 privilèges d'opérateur sont ajoutés par l'opérateur mobile dans les métadonnées de profil. L'API eUICC applique les règles concernant les privilèges de l'opérateur en conséquence.

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

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

API

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

Obtenir l'instance (public)

Récupère 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 (public)

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. Ce champ peut être nul si l'eUICC n'est pas prêt. L'appelant doit disposer du droit de 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.
}

Obtenir 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();

Abonnement de téléchargement (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 extrait 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 de l'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)

Active l'abonnement donné. L'appelant doit disposer de WRITE_EMBEDDED_SUBSCRIPTIONS ou de 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 un port (public)

(Disponible à partir d'Android 13) Bascule vers (active) l'abonnement donné avec l'index de port spécifié. L'appelant doit disposer de WRITE_EMBEDDED_SUBSCRIPTIONS ou de privilèges 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 */, 0 /*portIndex*/, callbackIntent);

Le port SIM est-il disponible (public) ?

public boolean isSimPortAvailable(int portIndex)

(À partir d'Android 13) Indique si l'index de port de transmission est disponible. Un port est disponible si aucun abonnement n'est activé ou si l'application appelante dispose d'un privilège opérateur sur l'abonnement installé sur le port sélectionné. Pour plus d'informations, consultez isSimPortAvailable.

Supprimer l'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 d'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 d'un appareil. À partir d'Android 11, vous devez fournir une valeur d'énumération EuiccCardManager#ResetOption pour spécifier si tous les types d'abonnements de test, opérationnels ou les deux doivent être effacés. 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 l'activité de résolution (public)

Démarre une activité pour résoudre une erreur pouvant être résolue par l'utilisateur. 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 particulière.

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

Constantes

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