eUICC APIs

In Android 9 sind APIs zur Profilverwaltung (öffentlich und @SystemApi) über die Klasse EuiccManager verfügbar. eUICC-Kommunikations-APIs (@SystemApi only) sind über die Klasse EuiccCardManager verfügbar.

Informationen zur eUICC

Mobilfunkanbieter können mit EuiccManager Mobilfunkanbieter-Apps erstellen, um Profile zu verwalten, wie in Abbildung 1 dargestellt. Carrier-Apps müssen keine System-Apps sein, aber sie benötigen Carrier-Berechtigungen, die von eUICC-Profilen gewährt werden. Eine LPA-App (LUI und LPA-Backend) muss eine System-App sein (d.h. im System-Image enthalten), um @SystemApi aufzurufen.

Android-Smartphone mit Mobilfunkanbieter-App und OEM-LPA

Abbildung 1: Android-Smartphones mit Mobilfunkanbieter-App und OEM-LPA

Neben der Logik für den Aufruf von EuiccCardManager und die Kommunikation mit der eUICC müssen LPA-Apps Folgendes implementieren:

  • SM-DP+-Client kommuniziert mit SM-DP+-Server, um Profile zu authentifizieren und herunterzuladen
  • [Optional] SM-DS, um weitere potenzielle herunterladbare Profile zu erhalten
  • Benachrichtigungen verarbeiten, um Benachrichtigungen an den Server zu senden und den Profilstatus zu aktualisieren
  • [Optional] Slot-Verwaltung, einschließlich des Wechsels zwischen eSIM- und pSIM-Logik. Das ist optional, wenn das Smartphone nur einen eSIM-Chip hat.
  • eSIM OTA

Auf einem Android-Smartphone können zwar mehrere LPA-Apps vorhanden sein, aber nur eine LPA kann als tatsächliche Arbeits-LPA ausgewählt werden. Die Auswahl erfolgt anhand der Priorität, die in der AndroidManifest.xml-Datei jeder App definiert ist.

EuiccManager verwenden

Die LPA-APIs sind über EuiccManager (im Paket android.telephony.euicc) öffentlich. Eine Carrier-App kann die Instanz von EuiccManager abrufen und die Methoden in EuiccManager aufrufen, um die eUICC-Informationen abzurufen und Abos (in GSMA RSP-Dokumenten als Profile bezeichnet) als SubscriptionInfo-Instanzen zu verwalten.

Damit öffentliche APIs aufgerufen werden können, einschließlich Vorgängen zum Herunterladen, Wechseln und Löschen von Abonnements, muss die Carrier-App die erforderlichen Berechtigungen haben. Mobilfunkanbieter fügen die Berechtigungen in den Profilmetadaten hinzu. Die eUICC-API setzt die Regeln für Betreiberberechtigungen entsprechend durch.

Die Android-Plattform verarbeitet die Profilrichtlinienregeln nicht. Wenn in den Profilmetadaten eine Richtlinienregel deklariert ist, kann der LPA entscheiden, wie er den Download und die Installation des Profils handhabt. Beispielsweise kann eine LPA eines Drittanbieter-OEM Richtlinienregeln mit einem speziellen Fehlercode verarbeiten. Der Fehlercode wird von der OEM-LPA an die Plattform und dann von der Plattform an die OEM-LUI übergeben.

Informationen zu mehreren aktivierten Profil-APIs finden Sie unter Mehrere aktivierte Profile.

APIs

Die folgenden APIs finden Sie in der Referenzdokumentation zu EuiccManager und EuiccManager.java.

Instanz abrufen (öffentlich)

Ruft die Instanz von EuiccManager über Context#getSystemService ab. Weitere Informationen finden Sie unter getSystemService.

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

Prüfung aktiviert (öffentlich)

Prüft, ob das eingebettete Abo aktiviert ist. Dies sollte vor dem Zugriff auf LPA-APIs geprüft werden. Weitere Informationen finden Sie unter isEnabled.

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

EID (öffentlich) abrufen

Ruft die EID ab, die die eUICC-Hardware identifiziert. Dieser Wert kann „null“ sein, wenn die eUICC nicht bereit ist. Der Aufrufer muss das Betreiberprivileg oder die Berechtigung READ_PRIVILEGED_PHONE_STATE haben. Weitere Informationen finden Sie unter getEid.

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

EuiccInfo abrufen (öffentlich)

Ruft Informationen zur eUICC ab. Diese enthält die Betriebssystemversion. Weitere Informationen finden Sie unter getEuiccInfo.

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

Abo herunterladen (öffentlich)

Lädt das angegebene Abo herunter (in GSMA RSP-Dokumenten als „Profil“ bezeichnet). Das Abo kann über einen Aktivierungscode erstellt werden. Beispielsweise kann ein Aktivierungscode aus einem QR-Code geparst werden. Das Herunterladen eines Abos ist ein asynchroner Vorgang.

Der Aufrufer muss entweder die Berechtigung WRITE_EMBEDDED_SUBSCRIPTIONS oder Betreiberberechtigungen für das Zielabo haben. Weitere Informationen finden Sie unter 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);

Abo wechseln (öffentlich)

Wechselt zum angegebenen Abo (aktiviert es). Der Anrufer muss entweder WRITE_EMBEDDED_SUBSCRIPTIONS haben oder Betreiberberechtigungen für das aktuelle aktivierte Abo und das Zielabo. Weitere Informationen finden Sie unter 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);

Abo mit Portierung wechseln (öffentlich)

(Verfügbar ab Android 13) Wechselt zum angegebenen Abo mit dem angegebenen Portindex (aktiviert es). Der Anrufer muss entweder die Berechtigung WRITE_EMBEDDED_SUBSCRIPTIONS oder Betreiberberechtigungen für das aktuell aktivierte Abo und das Zielabo haben. Weitere Informationen finden Sie unter 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);

Ist der SIM-Port verfügbar (öffentlich)?

public boolean isSimPortAvailable(int portIndex)

(Ab Android 13 verfügbar) Gibt zurück, ob der Index des Passing-Ports verfügbar ist. Ein Port ist verfügbar, wenn für ihn kein Abo aktiviert ist oder die Anruf-App das Betreiberprivileg für das auf dem ausgewählten Port installierte Abo hat. Weitere Informationen finden Sie unter isSimPortAvailable.

Abo löschen (öffentlich)

Löscht ein Abo mit einer Abo-ID. Wenn das Abo derzeit aktiv ist, wird es zuerst deaktiviert. Der Anrufer muss entweder WRITE_EMBEDDED_SUBSCRIPTIONS oder Betreiberberechtigungen für das Zielabo haben. Weitere Informationen finden Sie unter 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);

Alle Abos löschen (System-API)

Löscht alle Abos auf einem Gerät. Ab Android 11 sollten Sie einen EuiccCardManager#ResetOption-Enum-Wert angeben, um festzulegen, ob alle Test-, Betriebs- oder beide Arten von Abos gelöscht werden sollen. Der Aufrufer muss die Berechtigung WRITE_EMBEDDED_SUBSCRIPTIONS haben.

// 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);

Lösungsprozess starten (öffentlich)

Startet eine Aktivität, um einen vom Nutzer behebbaren Fehler zu beheben. Wenn bei einem Vorgang EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR zurückgegeben wird, kann diese Methode aufgerufen werden, um den Nutzer aufzufordern, das Problem zu beheben. Diese Methode kann für einen bestimmten Fehler nur einmal aufgerufen werden.

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

Konstanten

Eine Liste der public-Konstanten in EuiccManager finden Sie unter Konstanten.