API eUICC

Sous Android 9, les API de gestion de profil (publique 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 le montre la figure 1. Les applications d'opérateur ne doivent pas nécessairement être des applications système, mais doivent disposer des privilèges d'opérateur accordés par les profils eUICC. Une application LPA (backend LUI et 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 Carrier et OEM LPA

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

Outre la logique d'appeler EuiccCardManager et de parler à eUICC, les applications LPA doivent implémenter les éléments suivants :

  • Client SM-DP+ parlant au serveur SM-DP+ pour authentifier et télécharger des profils
  • [Facultatif] SM-DS pour obtenir davantage de profils téléchargeables potentiels
  • Gestion des notifications pour envoyer des notifications au serveur pour mettre à jour l'état du profil
  • [Facultatif] Gestion des emplacements, y compris la commutation entre la logique eSIM et pSIM. Ceci est facultatif si le téléphone dispose uniquement d’une puce eSIM.
  • eSIM OTA

Bien que plusieurs applications LPA puissent être présentes sur un téléphone Android, un seul LPA peut être sélectionné comme LPA réellement 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 privilèges requis. Les privilèges de l'opérateur sont ajoutés par l'opérateur de téléphonie 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 plateforme Android ne gère pas les règles de politique de profil. Si une règle de politique 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'interface utilisateur LUI OEM).

Pour plus d'informations sur les API de plusieurs profils activés, voir Plusieurs profils activés .

Apis

Les API suivantes peuvent être trouvées dans la documentation de référence EuiccManager et EuiccManager.java .

Obtenir une instance (publique)

Obtient l'instance d' EuiccManager via Context#getSystemService . Pour plus de détails, consultez getSystemService .

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

Chèque activé (public)

Vérifie si l'abonnement intégré est activé. Cela doit être vérifié avant d'accéder aux API LPA. Pour plus de détails, consultez isEnabled .

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

Obtenir l'EID (public)

Obtient l'EID identifiant le matériel eUICC. Cela peut être nul si l'eUICC n'est pas prêt. L'appelant doit disposer du privilège de l'opérateur ou de l'autorisation READ_PRIVILEGED_PHONE_STATE . Pour plus de détails, consultez getEid .

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

Obtenir EuiccInfo (public)

Obtient des informations sur l’eUICC. Celui-ci contient la version du système d'exploitation. Pour plus de détails, consultez getEuiccInfo .

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

Abonnement à télécharger (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 disposer des privilèges d’opérateur pour l’abonnement cible. Pour plus de détails, 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);

Abonnement Switch (public)

Bascule vers (active) l’abonnement donné. L'appelant doit disposer de WRITE_EMBEDDED_SUBSCRIPTIONS ou disposer des privilèges d'opérateur pour l'abonnement actuellement activé et l'abonnement cible. Pour plus de détails, 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);

Abonnement Switch avec 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 disposer des privilèges d'opérateur pour l'abonnement actuellement activé et l'abonnement cible. Pour plus de détails, 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 si aucun abonnement n'est activé ou si l'application appelante dispose du privilège de l'opérateur sur l'abonnement installé sur le port sélectionné. Pour plus de détails, 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 de WRITE_EMBEDDED_SUBSCRIPTIONS ou de privilèges d'opérateur pour l'abonnement cible. Pour plus de détails, 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 types d’abonnements de test, opérationnels ou les deux. 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 (publique)

Démarre une activité pour résoudre une erreur résoluble 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 voir une liste des constantes public dans EuiccManager , voir Constants .