eUICC API'leri

Android 9'da profil yönetimi API'leri (herkese açık ve @SystemApi), EuiccManager sınıfı aracılığıyla kullanılabilir. eUICC iletişim API'leri (yalnızca @SystemApi), EuiccCardManager sınıfı aracılığıyla kullanılabilir.

eUICC hakkında

Operatörler, Şekil 1'de gösterildiği gibi profilleri yönetmek için EuiccManager'ı kullanarak operatör uygulamaları oluşturabilir. Operatör uygulamalarının sistem uygulaması olması gerekmez ancak eUICC profilleri tarafından verilen operatör ayrıcalıklarına sahip olması gerekir. @SystemApi'yi çağırabilmek için LPA uygulamasının (LUI ve LPA arka ucu) sistem uygulaması (ör. sistem görüntüsüne dahil edilmiş) olması gerekir.

Operatör uygulaması ve OEM LPA yüklü Android telefon

Şekil 1. Operatör uygulaması ve OEM LPA'nın yüklü olduğu Android telefonlar

LPA uygulamaları, EuiccCardManager'ü arama ve eUICC ile konuşma mantığının yanı sıra aşağıdakileri de uygulamalıdır:

  • SM-DP+ istemcisi, kimlik doğrulamak ve profilleri indirmek için SM-DP+ sunucusuyla iletişim kuruyor
  • [İsteğe bağlı] Daha fazla indirilebilir profil elde etmek için SM-DS
  • Profil durumunu güncellemek için sunucuya bildirim gönderen bildirim işleme
  • [İsteğe bağlı] eSIM ve pSIM mantığı arasında geçiş de dahil olmak üzere yuva yönetimi. Telefonda yalnızca eSIM çipi varsa bu işlem isteğe bağlıdır.
  • eSIM OTA

Bir Android telefonda birden fazla LPA uygulaması bulunabilir ancak her uygulamanın AndroidManifest.xml dosyasında tanımlanan önceliğe göre yalnızca bir LPA, gerçek çalışan LPA olarak seçilebilir.

EuiccManager'ı kullanma

LPA API'leri, EuiccManager üzerinden (android.telephony.euicc paketi altında) herkese açıktır. Bir operatör uygulaması, EuiccManager örneğini alabilir ve eUICC bilgilerini almak ve abonelikleri (GSMA RSP belgelerinde profil olarak adlandırılır) SubscriptionInfo örnekleri olarak yönetmek için EuiccManager'teki yöntemleri çağırabilir.

Abonelik işlemlerini indirme, değiştirme ve silme dahil olmak üzere herkese açık API'leri çağırabilmek için operatör uygulamasının gerekli ayrıcalıklara sahip olması gerekir. Operatör ayrıcalıkları, mobil operatör tarafından profil meta verilerine eklenir. eUICC API'si, operatör ayrıcalık kurallarını buna göre uygular.

Android platformu, profil politikası kurallarını işlemez. Profil meta verilerinde bir politika kuralı tanımlanırsa LPA, profil indirme ve yükleme prosedürünü nasıl işleyeceğini seçebilir. Örneğin, üçüncü taraf OEM LPA'nın özel bir hata kodu kullanarak politika kurallarını işleyebilmesi mümkündür (hata kodu OEM LPA'dan platforma, ardından platform tarafından OEM LUI'ye iletilir).

Birden fazla etkin profil API'si hakkında bilgi edinmek için Birden çok etkin profil bölümüne bakın.

API'ler

Aşağıdaki API'ler EuiccManager referans dokümanlarında ve EuiccManager.java'te bulunabilir.

Örnek alma (herkese açık)

EuiccManager ile Context#getSystemService arasındaki örneği alır. Ayrıntılar için getSystemService sayfasına göz atın.

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

Kontrol etkin (herkese açık)

Yerleştirilmiş aboneliğin etkinleştirilip etkinleştirilmediğini kontrol eder. Bu, LPA API'lerine erişmeden önce kontrol edilmelidir. Ayrıntılar için isEnabled sayfasına göz atın.

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

SIM kimliği alın (herkese açık)

eUICC donanımını tanımlayan EID'yi alır. eUICC hazır değilse bu değer null olabilir. Arayanın operatör ayrıcalığı veya READ_PRIVILEGED_PHONE_STATE izni olması gerekir. Ayrıntılı bilgi için getEid başlıklı makaleyi inceleyin.

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

EuiccInfo Alma (herkese açık)

eUICC hakkında bilgi alır. İşletim sistemi sürümünü içerir. Ayrıntılı bilgi için getEuiccInfo başlıklı makaleyi inceleyin.

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

Aboneliği indirme (herkese açık)

Belirtilen aboneliği (GSMA RSP belgelerinde "profil" olarak adlandırılır) indirir. Abonelik, etkinleştirme koduyla oluşturulabilir. Örneğin, bir QR kodundan etkinleştirme kodu ayrıştırılabilir. Abonelik indirme işlemi eşzamansızdır.

Arayanın WRITE_EMBEDDED_SUBSCRIPTIONS iznine veya hedef abonelik için operatör ayrıcalıklarına sahip olması gerekir. Ayrıntılı bilgi için downloadSubscription başlıklı makaleyi inceleyin.

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

Abonelik değiştirme (herkese açık)

Belirtilen aboneliğe geçer (etkinleştirir). Arayan kullanıcının, etkin durumdaki mevcut abonelik ve hedef abonelik için WRITE_EMBEDDED_SUBSCRIPTIONS veya operatör ayrıcalıklarına sahip olması gerekir. Ayrıntılı bilgi için switchToSubscription başlıklı makaleyi inceleyin.

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

Aboneliği bağlantı noktasıyla değiştirme (herkese açık)

(Android 13'ten itibaren kullanılabilir) Belirtilen bağlantı noktası dizini ile belirli bir aboneliğe geçer (aboneliği etkinleştirir). Arayan kullanıcının, etkin durumdaki mevcut abonelik ve hedef abonelik için WRITE_EMBEDDED_SUBSCRIPTIONS veya operatör ayrıcalıklarına sahip olması gerekir. Ayrıntılı bilgi için switchToSubscription başlıklı makaleyi inceleyin.

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

SIM bağlantı noktası kullanılabilir mi (herkese açık)

public boolean isSimPortAvailable(int portIndex)

(Android 13'ten itibaren kullanılabilir) Geçiş bağlantı noktası dizininin kullanılabilir olup olmadığını döndürür. Bağlantı noktası, abonelik etkin değilse veya arayan uygulamanın, seçilen bağlantı noktasında yüklü abonelik üzerinde operatör ayrıcalığı varsa kullanılabilir. Ayrıntılı bilgi için isSimPortAvailable başlıklı makaleyi inceleyin.

Aboneliği silme (herkese açık)

Abonelik kimliği olan bir aboneliği siler. Abonelik şu anda etkin durumdaysa önce devre dışı bırakılır. Arayan, hedef abonelik için WRITE_EMBEDDED_SUBSCRIPTIONS veya operatör ayrıcalıklarına sahip olmalıdır. Ayrıntılı bilgi için deleteSubscription başlıklı makaleyi inceleyin.

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

Tüm abonelikleri silme (sistem API'si)

Cihazdaki tüm abonelikleri siler. Android 11'den itibaren, tüm test, operasyonel veya her iki abonelik türünün de silinip silinmeyeceğini belirtmek için bir EuiccCardManager#ResetOptionenum değeri sağlamanız gerekir. Arayanın WRITE_EMBEDDED_SUBSCRIPTIONS iznine sahip olması gerekir.

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

Çözüm etkinliği başlatma (herkese açık)

Kullanıcı tarafından çözülebilen bir hatayı çözmek için bir etkinlik başlatır. Bir işlem EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR döndürürse kullanıcıdan sorunu çözmesini istemek için bu yöntem çağrılabilir. Bu yöntem, belirli bir hata için yalnızca bir kez çağrılabilir.

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

Sabitler

EuiccManager içindeki public sabitlerinin listesini görmek için Sabitler bölümüne bakın.