API eUICC

Dans Android 9, les API de gestion des profils (publiques et @SystemApi) sont disponibles via la classe EuiccManager. Communication eUICC Les API (@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é comme indiqué dans la figure 1. Les applications d'opérateur ne doivent pas nécessairement être des applications système, mais doivent être associées à l'opérateur droits accordés par les profils eUICC. Une Application LPA (LUI et LPA) backend) doit être une application système (incluse dans l'image système) pour appeler @SystemApi.

Téléphone Android avec appli 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 eUICC, les applications LPA doit mettre en œuvre les éléments suivants:

  • Le client SM-DP+ communique avec le serveur SM-DP+ pour s'authentifier télécharger des profils
  • [Facultatif] SM-DS pour obtenir d'autres profils téléchargeables potentiels
  • Gestion des notifications pour envoyer des notifications au serveur à 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.
  • OTA eSIM

Bien que plusieurs applications LPA puissent être présentes dans un téléphone Android, une seule LPA peut être présente peut être sélectionné comme LPA actif 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 (appelés profils dans les documents RSP de la GSMA) sous le nom les instances SubscriptionInfo.

Pour appeler des API publiques, y compris télécharger, changer d'abonnement et supprimer l'abonnement l'application de l'opérateur doit disposer des droits requis. Opérateur les droits sont ajoutés par l'opérateur de téléphonie mobile dans les métadonnées du profil. L'eUICC L'API applique les règles relatives aux privilèges de l'opérateur en conséquence.

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

Pour en savoir plus sur l'utilisation de plusieurs API de profils activés, consultez Plusieurs profils activés :

API

Vous trouverez les API suivantes dans le Documentation de référence sur EuiccManager et EuiccManager.java

Obtenir l'instance (publique)

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 (publique)

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

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

Obtenir l'EID (public)

Récupère l'EID identifiant le matériel eUICC. Elle peut être nulle si l'eUICC est pas encore prêt. L'appelant doit disposer d'un droit d'opérateur ou Autorisation READ_PRIVILEGED_PHONE_STATE. Pour en savoir plus, consultez getEid

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

Get EuiccInfo (public)

Récupère des informations sur l'eUICC. Ce champ indique la version de l'OS. Pour en savoir plus, voir getEuiccInfo

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

Télécharger l'abonnement (public)

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

L'appelant doit disposer de l'autorisation WRITE_EMBEDDED_SUBSCRIPTIONS ou disposer de 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)

Bascule sur (active) l'abonnement donné. L'appelant doit avoir : WRITE_EMBEDDED_SUBSCRIPTIONS ou vous disposez de droits d'opérateur pour la période abonnement activé 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);

Switch subscription avec port (public)

(Disponible à partir d'Android 13) Passe à (activé) l'abonnement donné avec l'index de port spécifié. L'appelant doit être associé à un opérateur WRITE_EMBEDDED_SUBSCRIPTIONS ou à un opérateur droits pour l'abonnement actuellement activé 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);

Un port SIM est-il disponible (public)

public boolean isSimPortAvailable(int portIndex)

(Disponible à partir d'Android 13) Indique si le la transmission d'un index de port est disponible. Un port est disponible s'il n'a pas d'abonnement activé ou que l'application appelante dispose d'un droit d'opérateur sur le installé sur le port sélectionné. Pour plus d'informations, consultez isSimPortAvailable.

Supprimer l'abonnement (public)

Supprime un abonnement associé à un ID d'abonnement. Si l'abonnement est actuellement actif, il est d'abord désactivé. L'appelant doit avoir : WRITE_EMBEDDED_SUBSCRIPTIONS ou droits d'opérateur pour la cible abonnement. 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 un EuiccCardManager#ResetOption pour spécifier si vous souhaitez effacer tous les types de tests, opérationnels ou les deux abonnements. 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 pouvant être résolue par l'utilisateur. Si une opération renvoie EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR, cette méthode peut être appelé pour inviter l'utilisateur à résoudre le problème. Cette méthode ne peut être appelée pour chaque erreur.

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

Constantes

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