eUICC-APIs

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

eUICC

Mobilfunkanbieter können mit EuiccManager Profile in ihren Apps verwalten, wie in Abbildung 1 dargestellt. Mobilfunkanbieter-Apps müssen keine System-Apps sein, aber Mobilfunkanbieter-Berechtigungen haben, die über eUICC-Profile gewährt werden. Eine LPA-Anwendung (LUI- und LPA-Back-End) muss eine Systemanwendung sein (d.h. im System-Image enthalten), um die @SystemApi aufzurufen.

Android-Smartphone mit Mobilfunkanbieter-App und OEM-LPA

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

Neben der Logik zum Aufrufen von EuiccCardManager und zum Kommunizieren 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 mehr potenziell herunterladbare Profile zu erhalten
  • Benachrichtigungsverwaltung, um Benachrichtigungen an den Server zu senden, um den Profilstatus zu aktualisieren
  • [Optional] Slotverwaltung, einschließlich Wechsel zwischen eSIM und pSIM-Logik. Das ist optional, wenn das Smartphone nur einen eSIM-Chip hat.
  • eSIM OTA

Auf einem Android-Smartphone kann es zwar mehrere LPA-Apps geben, aber nur eine davon kann als aktive LPA-App ausgewählt werden. Die Auswahl erfolgt anhand der Priorität, die in der AndroidManifest.xml-Datei der jeweiligen App definiert ist.

EuiccManager verwenden

Die LPA APIs sind über EuiccManager öffentlich (unter Paket android.telephony.euicc). Eine Mobilfunkanbieter-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.

Zum Aufrufen öffentlicher APIs, einschließlich Download, Wechsel und Löschen von Abovorgängen, muss die Mobilfunkanbieter-App die erforderlichen Berechtigungen haben. Mobilfunkanbieterberechtigungen werden vom Mobilfunkanbieter in die Profilmetadaten eingefügt. Die eUICC API erzwingt die Berechtigungsregeln des Mobilfunkanbieters entsprechend.

Die Android-Plattform verarbeitet die Regeln für die Richtlinien für Profile nicht. Wenn in den Profilmetadaten eine Richtlinienregel deklariert ist, kann der LPA festlegen, wie der Download und die Installation des Profils erfolgen soll. So kann beispielsweise eine OEM-LPA eines Drittanbieters Richtlinienregeln mit einem speziellen Fehlercode verarbeiten. Der Fehlercode wird von der OEM-LPA an die Plattform übergeben, die ihn dann an die OEM-LUI weitergibt.

Informationen zu APIs für mehrere aktivierte Profile 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. Das 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 Anrufer muss die Berechtigung des Mobilfunkanbieters oder die Berechtigung READ_PRIVILEGED_PHONE_STATE haben. Weitere Informationen finden Sie unter getEid.

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

Get EuiccInfo (public)

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)

Das angegebene Abo wird heruntergeladen (in GSMA RSP-Dokumenten als „Profil“ bezeichnet). Das Abo kann über einen Aktivierungscode erstellt werden. So kann beispielsweise 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 die Mobilfunkanbieterberechtigungen 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 Aufrufer muss entweder WRITE_EMBEDDED_SUBSCRIPTIONS oder Mobilfunkanbieterberechtigungen 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 */, callbackIntent);

Abo mit Port wechseln (öffentlich)

(Verfügbar ab Android 13) Wechselt zu (aktiviert) dem angegebenen Abo mit dem angegebenen Portindex. Der Anrufer muss entweder WRITE_EMBEDDED_SUBSCRIPTIONS oder Berechtigungen des Mobilfunkanbieters 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)

(Verfügbar ab Android 13) Gibt an, ob der übergebene Portindex verfügbar ist. Ein Anschluss ist verfügbar, wenn kein Abo aktiviert ist oder die anrufende App Berechtigungen des Mobilfunkanbieters für das Abo hat, das auf dem ausgewählten Anschluss installiert ist. 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 Mobilfunkanbieterberechtigungen 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)

Alle Abos auf einem Gerät werden gelöscht. Ab Android 11 sollten Sie einen EuiccCardManager#ResetOption-Enum-Wert angeben, um anzugeben, 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);

Aktivität zur Problembehebung starten (öffentlich)

Startet eine Aktivität, um einen vom Nutzer behebbaren Fehler zu beheben. Wenn ein Vorgang EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR zurückgibt, 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.