eUICC API

Di Android 9, API pengelolaan profil (publik dan @SystemApi) tersedia melalui class EuiccManager. Komunikasi eUICC API (khusus @SystemApi) tersedia melalui class 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 operator hak istimewa yang diberikan oleh profil eUICC. Channel Aplikasi LPA (LUI dan LPA backend) harus berupa aplikasi sistem (yaitu, disertakan dalam image sistem) untuk memanggil @SystemApi.

Ponsel Android dengan Aplikasi Operator dan LPA OEM

Gambar 1. Ponsel Android dengan aplikasi operator dan LPA OEM

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

  • Klien SM-DP+ berbicara dengan server SM-DP+ untuk mengautentikasi dan download profil
  • [Opsional] SM-DS untuk mendapatkan lebih banyak profil potensial yang dapat didownload
  • Penanganan pemberitahuan untuk mengirimkan pemberitahuan ke server memperbarui status profil
  • [Opsional] Pengelolaan slot termasuk beralih antara logika eSIM dan pSIM. Tindakan ini bersifat opsional jika ponsel hanya memiliki chip eSIM.
  • OTA eSIM

Meskipun ada lebih dari satu aplikasi LPA yang dapat hadir di ponsel Android, hanya satu LPA dapat dipilih menjadi LPA kerja aktual berdasarkan prioritas yang ditetapkan dalam file AndroidManifest.xml dari setiap aplikasi.

Menggunakan EuiccManager

LPA API bersifat publik melalui EuiccManager (di bagian 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 GSMA RSP) sebagai Instance SubscriptionInfo.

Untuk memanggil API publik termasuk download, beralih, dan hapus langganan aplikasi operator harus memiliki hak istimewa yang diperlukan. Ekspedisi hak istimewa ditambahkan oleh operator seluler di metadata profil. eUICC API menerapkan aturan hak istimewa operator sebagaimana mestinya.

Platform Android tidak menangani aturan kebijakan profil. Jika aturan kebijakan dideklarasikan dalam metadata profil, LPA dapat memilih cara menangani download profil dan prosedur instalasi. Misalnya, sebuah aplikasi LPA OEM pihak ketiga untuk menangani aturan kebijakan menggunakan kode error khusus (error kode diteruskan dari LPA OEM ke platform, lalu platform akan meneruskan kode ke LUI OEM).

Untuk informasi tentang beberapa API profil yang diaktifkan, lihat Beberapa profil yang diaktifkan.

API

API berikut dapat ditemukan di Dokumentasi referensi EuiccManager dan EuiccManager.java

Mendapatkan instance (publik)

Mendapatkan instance EuiccManager melalui Context#getSystemService. Untuk mengetahui detailnya, lihat getSystemService

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

Pemeriksaan diaktifkan (publik)

Memeriksa apakah langganan tersemat diaktifkan. Ini harus diperiksa sebelum mengakses API LPA. Untuk detailnya, lihat isEnabled.

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

Dapatkan EID (publik)

Mendapatkan EID yang mengidentifikasi hardware eUICC. Ini mungkin null jika eUICC belum siap. Penelepon harus memiliki hak istimewa operator atau Izin READ_PRIVILEGED_PHONE_STATE. Untuk mengetahui detailnya, lihat getEid

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

Mendapatkan EuiccInfo (publik)

Mendapatkan informasi tentang eUICC. File ini berisi versi OS. Untuk mengetahui detailnya, lihat getEuiccInfo

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

Download langganan (publik)

Mendownload langganan yang ditentukan (disebut sebagai "profil" di GSMA RSP yang informatif serta dipersonalisasi). Langganan dapat dibuat dari kode aktivasi. Sebagai contoh, kode aktivasi bisa diuraikan dari kode QR. Mengunduh merupakan operasi asinkron.

Pemanggil harus memiliki izin WRITE_EMBEDDED_SUBSCRIPTIONS atau memiliki hak istimewa operator untuk langganan target. Untuk mengetahui detailnya, lihat 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);

Beralih langganan (publik)

Beralih ke (mengaktifkan) langganan yang ditentukan. Pemanggil harus memiliki WRITE_EMBEDDED_SUBSCRIPTIONS atau miliki hak istimewa operator untuk versi saat ini langganan yang diaktifkan dan langganan target. Untuk mengetahui detailnya, lihat 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);

Beralih langganan dengan port (publik)

(Tersedia dari Android 13) Beralih ke (mengaktifkan) langganan yang diberikan dengan indeks porta yang ditentukan. Penelepon harus memiliki WRITE_EMBEDDED_SUBSCRIPTIONS atau memiliki operator hak istimewa untuk langganan yang diaktifkan saat ini dan langganan target. Untuk mengetahui detailnya, lihat 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);

Apakah port SIM tersedia (publik)

public boolean isSimPortAvailable(int portIndex)

(Tersedia dari Android 13) Menampilkan apakah tersedia indeks porta. Port tersedia jika tidak memiliki langganan yang diaktifkan atau aplikasi panggilan memiliki hak istimewa operator di atas langganan yang diinstal di port yang dipilih. Untuk detailnya, lihat isSimPortAvailable.

Hapus langganan (publik)

Menghapus langganan yang memiliki ID langganan. Jika langganan masih aktif, terlebih dahulu dinonaktifkan. Pemanggil harus memiliki WRITE_EMBEDDED_SUBSCRIPTIONS atau hak istimewa operator untuk target langganan Anda. Untuk mengetahui detailnya, lihat 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);

Hapus semua langganan (API sistem)

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

Memulai aktivitas resolusi (publik)

Memulai aktivitas untuk me-resolve error yang dapat diselesaikan pengguna. Jika operasi menampilkan 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.