API eUICC

Di Android 9, API pengelolaan profil (publik dan @SystemApi) tersedia melalui kelas EuiccManager . API komunikasi eUICC (@SystemApi saja) tersedia melalui kelas EuiccCardManager .

Tentang eUICC

Operator dapat membuat aplikasi operator menggunakan EuiccManager untuk mengelola profil, seperti yang ditunjukkan pada Gambar 1. Aplikasi operator tidak harus berupa aplikasi sistem tetapi harus memiliki hak istimewa operator yang diberikan oleh profil eUICC. Aplikasi LPA (LUI dan backend LPA) harus berupa aplikasi sistem (yaitu, termasuk dalam citra sistem) untuk memanggil @SystemApi.

Ponsel Android dengan Aplikasi Operator dan OEM LPA

Gambar 1. Ponsel Android dengan aplikasi operator dan OEM LPA

Selain logika memanggil EuiccCardManager dan berbicara dengan eUICC, aplikasi LPA harus menerapkan hal berikut:

  • Klien SM-DP+ berbicara dengan server SM-DP+ untuk mengotentikasi dan mengunduh profil
  • [Opsional] SM-DS untuk mendapatkan lebih banyak profil potensial yang dapat diunduh
  • Penanganan notifikasi untuk mengirim notifikasi ke server untuk memperbarui status profil
  • [Opsional] Manajemen slot termasuk beralih antara logika eSIM dan pSIM. Ini opsional jika ponsel hanya memiliki chip eSIM.
  • eSIM OTA

Meskipun lebih dari satu aplikasi LPA dapat hadir di ponsel Android, hanya satu LPA yang dapat dipilih untuk menjadi LPA yang bekerja sebenarnya berdasarkan prioritas yang ditentukan dalam file AndroidManifest.xml dari setiap aplikasi.

Menggunakan EuiccManager

API LPA bersifat publik melalui EuiccManager (di bawah paket android.telephony.euicc ). Aplikasi operator bisa mendapatkan instance EuiccManager , dan memanggil metode di EuiccManager untuk mendapatkan informasi eUICC dan mengelola langganan (disebut sebagai profil dalam dokumen RSP GSMA) sebagai instance SubscriptionInfo.

Untuk memanggil API publik termasuk mengunduh, beralih, dan menghapus operasi langganan, aplikasi operator harus memiliki hak istimewa yang diperlukan. Hak istimewa operator ditambahkan oleh operator seluler di metadata profil. API eUICC memberlakukan aturan hak istimewa operator yang sesuai.

Platform Android tidak menangani aturan kebijakan profil. Jika aturan kebijakan dideklarasikan dalam metadata profil, LPA dapat memilih cara menangani unduhan profil dan prosedur penginstalan. Misalnya, LPA OEM pihak ketiga dapat menangani aturan kebijakan menggunakan kode kesalahan khusus (kode kesalahan diteruskan dari LPA OEM ke platform, lalu platform meneruskan kode ke OEM LUI).

Lebah

API berikut dapat ditemukan di dokumentasi EuiccManager EuiccManager dan EuiccManager.java .

Dapatkan instance (publik)

Mendapatkan instance EuiccManager melalui Context#getSystemService .

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

Centang diaktifkan (publik)

Memeriksa apakah langganan tersemat diaktifkan. Ini harus diperiksa sebelum mengakses API LPA.

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

Dapatkan EID (publik)

Mendapatkan EID yang mengidentifikasi perangkat keras eUICC. Ini mungkin nol jika eUICC belum siap. Penelepon harus memiliki hak istimewa operator atau izin READ_PRIVILEGED_PHONE_STATE .

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

Dapatkan EuiccInfo (publik)

Mendapat informasi tentang eUICC. Ini berisi versi OS.

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

Unduh langganan (publik)

Mengunduh langganan yang diberikan (disebut sebagai "profil" dalam dokumen RSP GSMA). Langganan dapat dibuat dari kode aktivasi. Misalnya, kode aktivasi dapat diuraikan dari kode QR. Mengunduh langganan adalah operasi asinkron.

Penelepon harus memiliki izin WRITE_EMBEDDED_SUBSCRIPTIONS atau memiliki hak operator untuk langganan target.

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

Beralih langganan (publik)

Beralih ke (mengaktifkan) langganan yang diberikan. Penelepon harus memiliki WRITE_EMBEDDED_SUBSCRIPTIONS atau memiliki hak istimewa operator untuk langganan aktif saat ini dan langganan target.

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

Hapus langganan (publik)

Menghapus langganan dengan ID langganan. Jika langganan saat ini aktif, itu pertama kali dinonaktifkan. Penelepon harus memiliki WRITE_EMBEDDED_SUBSCRIPTIONS atau hak operator untuk langganan target.

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

Hapus semua langganan (API sistem)

Menghapus semua langganan di perangkat. Mulai Android 11, Anda harus memberikan nilai enum EuiccCardManager#ResetOption untuk menentukan apakah akan menghapus semua pengujian, operasional, atau kedua jenis langganan. Penelepon harus memiliki izin 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);

Mulai aktivitas resolusi (publik)

Memulai aktivitas untuk mengatasi kesalahan yang dapat diselesaikan pengguna. Jika operasi mengembalikan EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR , metode ini dapat dipanggil untuk meminta pengguna menyelesaikan masalah. Metode ini hanya dapat dipanggil sekali untuk kesalahan tertentu.

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

Konstanta

Untuk melihat daftar konstanta public di EuiccManager , lihat Konstanta .