Teknologi SIM tersemat (eSIM, atau eUICC) memungkinkan pengguna perangkat seluler mendownload profil operator dan mengaktifkan layanan operator tanpa memiliki kartu SIM fisik. Spesifikasi global ini didorong oleh GSMA yang memungkinkan penyediaan SIM jarak jauh (RSP) untuk perangkat seluler apa pun. Mulai Android 9, framework Android menyediakan API standar untuk mengakses eSIM dan mengelola profil langganan di eSIM. API eUICC ini memungkinkan pihak ketiga mengembangkan aplikasi operator dan asisten profil lokal (LPA) mereka sendiri di perangkat Android yang kompatibel dengan eSIM.
LPA adalah aplikasi sistem mandiri yang harus disertakan dalam image build Android. Pengelolaan profil di eSIM umumnya dilakukan oleh LPA, karena berfungsi sebagai jembatan antara SM-DP+ (layanan jarak jauh yang menyiapkan, menyimpan, dan mengirimkan paket profil ke perangkat) dan chip eUICC. APK LPA dapat secara opsional menyertakan komponen UI, yang disebut UI LPA atau LUI, untuk menyediakan tempat terpusat bagi pengguna akhir untuk mengelola semua profil langganan yang disematkan. Framework Android secara otomatis menemukan dan terhubung ke LPA terbaik yang tersedia, serta merutekan semua operasi eUICC melalui instance LPA.
Gambar 1. Arsitektur RSP yang disederhanakan
Operator jaringan seluler yang tertarik untuk membuat aplikasi operator harus melihat
API di
EuiccManager,
yang menyediakan operasi pengelolaan profil tingkat tinggi seperti
downloadSubscription(), switchToSubscription(), dan
deleteSubscription().
Jika Anda adalah OEM perangkat yang tertarik untuk membuat aplikasi sistem LPA sendiri, Anda harus memperluas
EuiccService
agar framework Android dapat terhubung ke layanan LPA Anda. Selain itu, Anda harus menggunakan API di EuiccCardManager, yang menyediakan fungsi ES10x berdasarkan GSMA RSP v2.0.
Fungsi ini digunakan untuk mengeluarkan perintah ke chip eUICC, seperti
prepareDownload(), loadBoundProfilePackage(), retrieveNotificationList(),
dan resetMemory().
API di
EuiccManager
memerlukan aplikasi LPA yang diimplementasikan dengan benar agar berfungsi dan pemanggil
API EuiccCardManager
harus berupa LPA. Hal ini diterapkan oleh framework Android.
Perangkat yang menjalankan Android 10 atau yang lebih tinggi dapat mendukung perangkat dengan beberapa eSIM. Untuk mengetahui informasi selengkapnya, lihat Mendukung beberapa eSIM.
Membuat aplikasi operator
API eUICC di Android 9 memungkinkan operator jaringan seluler membuat aplikasi bermerek operator untuk mengelola profil mereka secara langsung. Hal ini mencakup mendownload dan menghapus profil langganan yang dimiliki oleh operator, serta beralih ke profil yang dimiliki oleh operator.
EuiccManager
EuiccManager adalah titik entri utama bagi aplikasi untuk berinteraksi dengan
LPA. Hal ini mencakup aplikasi operator yang mendownload, menghapus, dan beralih ke langganan yang dimiliki oleh operator. Hal ini juga mencakup aplikasi sistem LUI, yang
menyediakan lokasi/UI terpusat untuk mengelola semua langganan sematan, dan
dapat berupa aplikasi terpisah dari aplikasi yang menyediakan EuiccService.
Untuk menggunakan API publik, aplikasi operator harus mendapatkan instance
EuiccManager melalui Context#getSystemService terlebih dahulu:
EuiccManager mgr = (EuiccManager) context.getSystemService(Context.EUICC_SERVICE);
Anda harus memeriksa apakah eSIM didukung di perangkat sebelum melakukan operasi eSIM. EuiccManager#isEnabled() umumnya menampilkan true jika fitur
android.hardware.telephony.euicc ditentukan dan paket LPA ada.
if (mgr == null || !mgr.isEnabled()) {
return;
}
Untuk mendapatkan informasi tentang hardware eUICC dan versi OS eSIM:
EuiccInfo info = mgr.getEuiccInfo();
String osVer = info.getOsVersion();
Banyak API, seperti downloadSubscription() dan switchToSubscription(), menggunakan callback PendingIntent karena mungkin memerlukan waktu beberapa detik atau bahkan menit untuk diselesaikan.
PendingIntent dikirim dengan kode hasil di ruang
EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_, yang menyediakan
kode error yang ditentukan framework, serta kode hasil mendetail arbitrer yang
dipropagasi dari LPA sebagai EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, sehingga
aplikasi operator dapat melacak untuk tujuan logging/pen-debug-an. Callback PendingIntent
harus berupa BroadcastReceiver.
Untuk mendownload langganan yang dapat didownload tertentu (dibuat dari kode aktivasi atau kode QR):
// Register receiver.
static final String ACTION_DOWNLOAD_SUBSCRIPTION = "download_subscription";
static final String LPA_DECLARED_PERMISSION
= "com.your.company.lpa.permission.BROADCAST";
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*/);
// If the result code is a resolvable error, call startResolutionActivity
if (resultCode == EuiccManager.EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR) {
PendingIntent callbackIntent = PendingIntent.getBroadcast(
getContext(), 0 /* requestCode */, intent,
PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_MUTABLE);
mgr.startResolutionActivity(
activity,
0 /* requestCode */,
intent,
callbackIntent);
}
resultIntent = intent;
}
};
context.registerReceiver(receiver,
new IntentFilter(ACTION_DOWNLOAD_SUBSCRIPTION),
LPA_DECLARED_PERMISSION /* broadcastPermission*/,
null /* handler */);
// Download subscription asynchronously.
DownloadableSubscription sub = DownloadableSubscription
.forActivationCode(code /* encodedActivationCode*/);
Intent intent = new Intent(action).setPackage(context.getPackageName());
PendingIntent callbackIntent = PendingIntent.getBroadcast(
getContext(), 0 /* requestCode */, intent,
PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_MUTABLE);
mgr.downloadSubscription(sub, true /* switchAfterDownload */,
callbackIntent);
Tentukan dan gunakan izin di AndroidManifest.xml:
<permission android:protectionLevel="signature" android:name="com.your.company.lpa.permission.BROADCAST" />
<uses-permission android:name="com.your.company.lpa.permission.BROADCAST"/>
Untuk beralih ke langganan dengan ID langganan tertentu:
// Register receiver.
static final String ACTION_SWITCH_TO_SUBSCRIPTION = "switch_to_subscription";
static final String LPA_DECLARED_PERMISSION
= "com.your.company.lpa.permission.BROADCAST";
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_SWITCH_TO_SUBSCRIPTION),
LPA_DECLARED_PERMISSION /* broadcastPermission*/,
null /* handler */);
// Switch to a subscription asynchronously.
Intent intent = new Intent(action).setPackage(context.getPackageName());
PendingIntent callbackIntent = PendingIntent.getBroadcast(
getContext(), 0 /* requestCode */, intent,
PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_MUTABLE);
mgr.switchToSubscription(1 /* subscriptionId */, callbackIntent);
Untuk mengetahui daftar lengkap API EuiccManager dan contoh kode, lihat API eUICC.
Error yang dapat diselesaikan
Ada beberapa kasus ketika sistem tidak dapat menyelesaikan operasi eSIM, tetapi error dapat diselesaikan oleh pengguna. Misalnya, downloadSubscription
dapat gagal jika metadata profil menunjukkan bahwa kode konfirmasi operator
diperlukan. Atau, switchToSubscription dapat gagal jika aplikasi operator memiliki hak istimewa operator atas profil tujuan (yaitu, operator memiliki profil) tetapi tidak memiliki hak istimewa operator atas profil yang saat ini diaktifkan, sehingga izin pengguna diperlukan.
Untuk kasus ini, callback pemanggil dipanggil dengan
EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR. Callback
Intent berisi ekstra internal sehingga saat pemanggil meneruskannya ke
EuiccManager#startResolutionActivity,
resolusi dapat diminta melalui LUI. Menggunakan kode konfirmasi untuk
contoh lagi,
EuiccManager#startResolutionActivity
memicu layar LUI yang memungkinkan pengguna memasukkan kode konfirmasi;
setelah kode dimasukkan, operasi download dilanjutkan. Pendekatan ini
memberi aplikasi operator kontrol penuh atas kapan UI ditampilkan, tetapi memberi
LPA/LUI metode yang dapat di-extend untuk menambahkan penanganan baru masalah yang dapat dipulihkan pengguna di masa mendatang tanpa perlu mengubah aplikasi klien.
Android 9 menentukan error yang dapat diselesaikan ini di
EuiccService,
yang harus ditangani oleh LUI:
/**
* Alert the user that this action will result in an active SIM being
* deactivated. To implement the LUI triggered by the system, you need to define
* this in AndroidManifest.xml.
*/
public static final String ACTION_RESOLVE_DEACTIVATE_SIM =
"android.service.euicc.action.RESOLVE_DEACTIVATE_SIM";
/**
* Alert the user about a download/switch being done for an app that doesn't
* currently have carrier privileges.
*/
public static final String ACTION_RESOLVE_NO_PRIVILEGES =
"android.service.euicc.action.RESOLVE_NO_PRIVILEGES";
/** Ask the user to resolve all the resolvable errors. */
public static final String ACTION_RESOLVE_RESOLVABLE_ERRORS =
"android.service.euicc.action.RESOLVE_RESOLVABLE_ERRORS";
Hak istimewa operator
Jika Anda adalah operator yang mengembangkan aplikasi operator sendiri yang memanggil EuiccManager
untuk mendownload profil ke perangkat, profil Anda harus menyertakan aturan hak istimewa operator yang sesuai dengan aplikasi operator Anda dalam metadata. Hal ini karena profil langganan milik operator yang berbeda dapat berada bersama di eUICC perangkat, dan setiap aplikasi operator hanya boleh mengakses profil yang dimiliki oleh operator tersebut. Misalnya, operator A tidak boleh dapat mendownload, mengaktifkan, atau menonaktifkan profil yang dimiliki oleh operator B.
Untuk memastikan profil hanya dapat diakses oleh pemiliknya, Android menggunakan mekanisme untuk memberikan hak istimewa khusus ke aplikasi pemilik profil (yaitu, aplikasi operator). Platform
Android memuat sertifikat yang disimpan dalam file aturan akses (ARF) profil
dan memberikan izin kepada aplikasi yang ditandatangani oleh sertifikat ini untuk melakukan panggilan
ke API EuiccManager. Proses tingkat tinggi dijelaskan di bawah:
- Operator menandatangani APK aplikasi operator; alat apksigner melampirkan sertifikat kunci publik ke APK.
Operator/SM-DP+ menyiapkan profil dan metadatanya, yang mencakup ARF yang berisi:
- Tanda tangan (SHA-1 atau SHA-256) sertifikat kunci publik aplikasi operator (wajib)
- Nama paket aplikasi operator (sangat direkomendasikan)
Aplikasi operator mencoba melakukan operasi eUICC dengan
EuiccManagerAPI.Platform Android memverifikasi apakah hash SHA-1 atau SHA-256 sertifikat aplikasi pemanggil cocok dengan tanda tangan sertifikat yang diperoleh dari ARF profil target. Jika nama paket aplikasi operator disertakan dalam ARF, nama paket tersebut juga harus cocok dengan nama paket aplikasi pemanggil.
Setelah tanda tangan dan nama paket (jika disertakan) diverifikasi, hak istimewa operator diberikan ke aplikasi pemanggil melalui profil target.
Karena metadata profil dapat tersedia di luar profil itu sendiri (sehingga LPA dapat mengambil metadata profil dari SM-DP+ sebelum profil didownload, atau dari ISD-R saat profil dinonaktifkan), metadata tersebut harus berisi aturan hak istimewa operator yang sama seperti di profil.
OS eUICC dan SM-DP+ harus mendukung tag eksklusif BF76 dalam metadata profil. Konten tag harus berupa aturan hak istimewa operator yang sama seperti yang ditampilkan oleh applet aturan akses (ARA) yang ditentukan dalam Hak Istimewa Operator UICC:
RefArDo ::= [PRIVATE 2] SEQUENCE { -- Tag E2
refDo [PRIVATE 1] SEQUENCE { -- Tag E1
deviceAppIdRefDo [PRIVATE 1] OCTET STRING (SIZE(20|32)), -- Tag C1
pkgRefDo [PRIVATE 10] OCTET STRING (SIZE(0..127)) OPTIONAL -- Tag CA
},
arDo [PRIVATE 3] SEQUENCE { -- Tag E3
permArDo [PRIVATE 27] OCTET STRING (SIZE(8)) -- Tag DB
}
}
Untuk mengetahui detail selengkapnya tentang penandatanganan aplikasi, lihat Menandatangani aplikasi Anda. Untuk mengetahui detail tentang hak istimewa operator, lihat Hak Istimewa Operator UICC.
Membuat aplikasi asisten profil lokal
Produsen perangkat dapat menerapkan asisten profil lokal (LPA) mereka sendiri, yang harus dihubungkan dengan Android Euicc API. Bagian berikut memberikan ringkasan singkat tentang cara membuat aplikasi LPA dan mengintegrasikannya dengan sistem Android.
Persyaratan hardware/modem
LPA dan OS eSIM pada chip eUICC harus mendukung setidaknya GSMA RSP (Remote SIM Provisioning) v2.0 atau v2.2. Anda juga harus berencana menggunakan server SM-DP+ dan SM-DS yang memiliki versi RSP yang cocok. Untuk arsitektur RSP yang mendetail, lihat Spesifikasi Arsitektur RSP SGP.21 GSMA.
Selain itu, untuk berintegrasi dengan eUICC API di Android 9, modem perangkat harus mengirimkan kemampuan terminal dengan dukungan untuk kemampuan eUICC yang dienkode (pengelolaan profil lokal dan download profil). Class ini juga perlu menerapkan metode berikut:
- IRadio HAL v1.1:
setSimPower IRadio HAL v1.2:
getIccCardStatusIRadioConfig HAL v1.0:
getSimSlotsStatusIRadioConfig AIDL v1.0:
getAllowedCarriersLPA Google perlu mengetahui status kunci operator agar dapat mengizinkan download atau transfer eSIM hanya untuk operator yang diizinkan. Jika tidak, pengguna mungkin mendownload dan mentransfer SIM, lalu menyadari bahwa perangkat tersebut dikunci oleh operator lain.
Vendor atau OEM harus mengimplementasikan IRadioSim.getAllowedCarriers()HAL API.
RIL / Modem Vendor akan mengisi status kunci dan carrierId operator tempat perangkat dikunci sebagai bagian dari IRadioSimResponse.getAllowedCarriersResponse() HAL API.
Modem harus mengenali eSIM dengan profil booting default yang diaktifkan sebagai SIM yang valid dan menjaga daya SIM tetap aktif.
Untuk perangkat yang menjalankan Android 10, array ID slot eUICC yang tidak dapat dilepas harus ditentukan. Misalnya, lihat
arrays.xml.
<resources>
<!-- Device-specific array of SIM slot indexes which are are embedded eUICCs.
e.g. If a device has two physical slots with indexes 0, 1, and slot 1 is an
eUICC, then the value of this array should be:
<integer-array name="non_removable_euicc_slots">
<item>1</item>
</integer-array>
If a device has three physical slots and slot 1 and 2 are eUICCs, then the value of
this array should be:
<integer-array name="non_removable_euicc_slots">
<item>1</item>
<item>2</item>
</integer-array>
This is used to differentiate between removable eUICCs and built in eUICCs, and should
be set by OEMs for devices which use eUICCs. -->
<integer-array name="non_removable_euicc_slots">
<item>1</item>
</integer-array>
</resources>
Untuk mengetahui daftar lengkap persyaratan modem, lihat Persyaratan Modem untuk Dukungan eSIM.
EuiccService
LPA terdiri dari dua komponen terpisah (keduanya dapat diimplementasikan dalam APK yang sama): backend LPA, dan UI LPA atau LUI.
Untuk mengimplementasikan backend LPA, Anda harus memperluas
EuiccService
dan mendeklarasikan layanan ini dalam file manifes Anda. Layanan harus memerlukan izin sistem android.permission.BIND_EUICC_SERVICE untuk memastikan bahwa hanya sistem yang dapat terikat ke layanan tersebut. Layanan juga harus menyertakan filter intent dengan
tindakan android.service.euicc.EuiccService. Prioritas filter
intent harus ditetapkan ke nilai bukan nol jika ada beberapa penerapan
di perangkat. Contoh:
<service
android:name=".EuiccServiceImpl"
android:permission="android.permission.BIND_EUICC_SERVICE">
<intent-filter android:priority="100">
<action android:name="android.service.euicc.EuiccService" />
</intent-filter>
</service>
Secara internal, framework Android menentukan LPA aktif dan berinteraksi dengannya sesuai kebutuhan untuk mendukung Android eUICC API. PackageManager dikueri untuk
semua aplikasi dengan izin android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS,
yang menentukan layanan untuk tindakan android.service.euicc.EuiccService.
Layanan dengan prioritas tertinggi akan dipilih. Jika tidak ada layanan yang ditemukan, dukungan LPA dinonaktifkan.
Untuk menerapkan LUI, Anda harus menyediakan aktivitas untuk tindakan berikut:
android.service.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONSandroid.service.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION
Seperti layanan, setiap aktivitas harus memerlukan izin sistem android.permission.BIND_EUICC_SERVICE. Setiap tindakan harus memiliki
filter intent dengan tindakan yang sesuai, kategori
android.service.euicc.category.EUICC_UI, dan prioritas bukan nol.
Logika serupa digunakan untuk memilih penerapan aktivitas ini seperti halnya memilih penerapan EuiccService.
Contoh:
<activity android:name=".MyLuiActivity"
android:exported="true"
android:permission="android.permission.BIND_EUICC_SERVICE">
<intent-filter android:priority="100">
<action android:name="android.service.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS" />
<action android:name="android.service.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.service.euicc.category.EUICC_UI" />
</intent-filter>
</activity>
Hal ini menyiratkan bahwa UI yang menerapkan layar ini dapat berasal dari APK yang berbeda dengan APK yang menerapkan
EuiccService.
Apakah akan memiliki satu APK atau beberapa APK (misalnya, satu yang menerapkan
EuiccService dan satu yang menyediakan aktivitas LUI) adalah pilihan desain.
EuiccCardManager
EuiccCardManager adalah antarmuka untuk berkomunikasi dengan chip eSIM. Library ini menyediakan fungsi ES10 (seperti yang dijelaskan dalam spesifikasi RSP GSMA) dan menangani perintah permintaan/respons APDU tingkat rendah serta parsing ASN.1.
EuiccCardManager adalah API sistem dan hanya dapat dipanggil oleh aplikasi
dengan hak istimewa sistem.
Gambar 2. Aplikasi operator dan LPA menggunakan Euicc API
API operasi profil melalui EuiccCardManager mengharuskan pemanggil menjadi
LPA. Hal ini diterapkan oleh framework Android. Artinya, pemanggil harus memperluas EuiccService dan dideklarasikan dalam file manifes Anda, seperti yang dijelaskan di bagian sebelumnya.
Mirip dengan EuiccManager, untuk menggunakan EuiccCardManager API, LPA Anda harus
mendapatkan instance EuiccCardManager terlebih dahulu melalui
Context#getSystemService:
EuiccCardManager cardMgr = (EuiccCardManager) context.getSystemService(Context.EUICC_CARD_SERVICE);
Kemudian, untuk mendapatkan semua profil di eUICC:
ResultCallback<EuiccProfileInfo[]> callback =
new ResultCallback<EuiccProfileInfo[]>() {
@Override
public void onComplete(int resultCode,
EuiccProfileInfo[] result) {
if (resultCode == EuiccCardManagerReflector.RESULT_OK) {
// handle result
} else {
// handle error
}
}
};
cardMgr.requestAllProfiles(eid, AsyncTask.THREAD_POOL_EXECUTOR, callback);
Secara internal, EuiccCardManager terikat ke EuiccCardController (yang berjalan dalam proses ponsel) melalui antarmuka AIDL, dan setiap metode EuiccCardManager menerima callback-nya dari proses ponsel melalui antarmuka AIDL khusus yang berbeda. Saat menggunakan API EuiccCardManager, pemanggil (LPA) harus menyediakan objek
Executor
yang digunakan untuk memanggil callback. Objek Executor ini dapat berjalan di satu thread atau di thread pool pilihan Anda.
Sebagian besar API EuiccCardManager memiliki pola penggunaan yang sama. Misalnya, untuk memuat paket profil terikat ke eUICC:
...
cardMgr.loadBoundProfilePackage(eid, boundProfilePackage,
AsyncTask.THREAD_POOL_EXECUTOR, callback);
Untuk beralih ke profil lain dengan ICCID tertentu:
...
cardMgr.switchToProfile(eid, iccid, true /* refresh */,
AsyncTask.THREAD_POOL_EXECUTOR, callback);
Untuk mendapatkan alamat SM-DP+ default dari chip eUICC:
...
cardMgr.requestDefaultSmdpAddress(eid, AsyncTask.THREAD_POOL_EXECUTOR,
callback);
Untuk mengambil daftar notifikasi dari peristiwa notifikasi tertentu:
...
cardMgr.listNotifications(eid,
EuiccNotification.Event.INSTALL
| EuiccNotification.Event.DELETE /* events */,
AsyncTask.THREAD_POOL_EXECUTOR, callback);
Mengaktifkan profil eSIM melalui aplikasi operator
Di perangkat yang menjalankan Android 9 atau yang lebih tinggi, Anda dapat menggunakan aplikasi operator untuk mengaktifkan eSIM dan mendownload profil. Aplikasi operator dapat mendownload profil dengan
memanggil
downloadSubscription
secara langsung atau dengan memberikan kode aktivasi ke LPA.
Saat aplikasi operator mendownload profil dengan memanggil
downloadSubscription,
panggilan tersebut memastikan bahwa aplikasi dapat mengelola profil melalui BF76
tag metadata
yang mengenkode aturan hak istimewa operator untuk
profil. Jika profil tidak memiliki tag BF76 atau jika tag BF76-nya tidak cocok dengan tanda tangan aplikasi operator panggilan, download akan ditolak.
Bagian di bawah menjelaskan cara mengaktifkan eSIM melalui aplikasi operator menggunakan kode aktivasi.
Mengaktifkan eSIM menggunakan kode aktivasi
Saat menggunakan kode aktivasi untuk mengaktifkan profil eSIM, LPA mengambil
kode aktivasi dari
aplikasi operator dan mendownload profil. Alur ini dapat dimulai oleh LPA
dan LPA dapat mengontrol seluruh alur UI, yang berarti tidak ada UI aplikasi operator yang
ditampilkan. Pendekatan ini melewati pemeriksaan tag BF76, dan operator jaringan tidak perlu menerapkan seluruh alur UI aktivasi eSIM, termasuk mendownload profil eSIM dan penanganan error.
Menentukan layanan penyediaan eUICC operator
Aplikasi operator dan LPA berkomunikasi melalui dua antarmuka
AIDL:
ICarrierEuiccProvisioningService dan IGetActivationCodeCallback. Aplikasi operator harus menerapkan antarmuka ICarrierEuiccProvisioningService dan mengeksposnya dalam deklarasi manifes.
LPA harus terikat ke ICarrierEuiccProvisioningService dan menerapkan
IGetActivationCodeCallback. Untuk mengetahui informasi selengkapnya tentang cara menerapkan dan mengekspos antarmuka AIDL, lihat Menentukan antarmuka AIDL.
Untuk menentukan antarmuka AIDL, buat file AIDL berikut untuk aplikasi LPA dan operator.
ICarrierEuiccProvisioningService.aidlpackage android.service.euicc; import android.service.euicc.IGetActivationCodeCallback; oneway interface ICarrierEuiccProvisioningService { // The method to get the activation code from the carrier app. The caller needs to pass in // the implementation of IGetActivationCodeCallback as the parameter. void getActivationCode(in IGetActivationCodeCallback callback); // The method to get the activation code from the carrier app. The caller needs to pass in // the activation code string as the first parameter and the implementation of // IGetActivationCodeCallback as the second parameter. This method provides the carrier // app the device EID which allows a carrier to pre-bind a profile to the device's EID before // the download process begins. void getActivationCodeForEid(in String eid, in IGetActivationCodeCallback callback); }IGetActivationCodeCallback.aidlpackage android.service.euicc; oneway interface IGetActivationCodeCallback { // The call back method needs to be called when the carrier app gets the activation // code successfully. The caller needs to pass in the activation code string as the // parameter. void onSuccess(String activationCode); // The call back method needs to be called when the carrier app failed to get the // activation code. void onFailure(); }
Contoh penerapan LPA
Untuk mengikat ke penerapan ICarrierEuiccProvisioningService aplikasi operator,
LPA harus menyalin ICarrierEuiccProvisioningService.aidl dan
IGetActivationCodeCallback.aidl ke project Anda dan menerapkan
ServiceConnection.
@Override
public void onServiceConnected(ComponentName componentName, IBinder iBinder) {
mCarrierProvisioningService = ICarrierEuiccProvisioningService.Stub.asInterface(iBinder);
}
Setelah terikat ke penerapan ICarrierEuiccProvisioningService
aplikasi operator, LPA memanggil getActivationCode atau
getActivationCodeForEid untuk mendapatkan kode aktivasi dari aplikasi operator dengan
meneruskan penerapan class stub IGetActivationCodeCallback.
Perbedaan antara getActivationCode dan getActivationCodeForEid adalah
getActivationCodeForEid memungkinkan operator mengikat profil ke EID perangkat
sebelum proses download dimulai.
void getActivationCodeFromCarrierApp() {
IGetActivationCodeCallback.Stub callback =
new IGetActivationCodeCallback.Stub() {
@Override
public void onSuccess(String activationCode) throws RemoteException {
// Handle the case LPA success to get activation code from a carrier app.
}
@Override
public void onFailure() throws RemoteException {
// Handle the case LPA failed to get activation code from a carrier app.
}
};
try {
mCarrierProvisioningService.getActivationCode(callback);
} catch (RemoteException e) {
// Handle Remote Exception
}
}
Contoh penerapan untuk aplikasi operator
Agar LPA terikat ke aplikasi operator, aplikasi operator harus menyalin ICarrierEuiccProvisioningService.aidl dan IGetActivationCodeCallback.aidl ke project Anda dan mendeklarasikan layanan ICarrierEuiccProvisioningService dalam file AndroidManifest.xml. Layanan harus memerlukan izin sistem
android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS untuk memastikan
bahwa hanya LPA, aplikasi dengan hak istimewa sistem, yang dapat terikat ke layanan tersebut. Layanan juga harus menyertakan filter intent dengan tindakan android.service.euicc.action.BIND_CARRIER_PROVISIONING_SERVICE.
AndroidManifest.xml<application> ... <service android:name=".CarrierEuiccProvisioningService" android:exported="true" android:permission="android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS"> <intent-filter> <action android:name="android.service.euicc.action.BIND_CARRIER_PROVISIONING_SERVICE"/> </intent-filter> </service> ... </application>
Untuk menerapkan layanan aplikasi operator AIDL, buat layanan, perluas class Stub, dan terapkan metode getActivationCode dan getActivationCodeForEid. LPA kemudian dapat memanggil salah satu metode untuk mengambil kode aktivasi
profil. Aplikasi operator harus merespons dengan memanggil
IGetActivationCodeCallback#onSuccess dengan kode aktivasi jika kode berhasil
diambil dari server operator. Jika tidak berhasil, aplikasi operator
harus merespons dengan IGetActivationCodeCallback#onFailure.
CarrierEuiccProvisioningService.javaimport android.service.euicc.ICarrierEuiccProvisioningService; import android.service.euicc.ICarrierEuiccProvisioningService.Stub; import android.service.euicc.IGetActivationCodeCallback; public class CarrierEuiccProvisioningService extends Service { private final ICarrierEuiccProvisioningService.Stub binder = new Stub() { @Override public void getActivationCode(IGetActivationCodeCallback callback) throws RemoteException { String activationCode = // do whatever work necessary to get an activation code (HTTP requests to carrier server, fetch from storage, etc.) callback.onSuccess(activationCode); } @Override public void getActivationCodeForEid(String eid, IGetActivationCodeCallback callback) throws RemoteException { String activationCode = // do whatever work necessary (HTTP requests, fetch from storage, etc.) callback.onSuccess(activationCode); } } }
Memulai UI aplikasi operator dalam alur aktivasi LPA
Di perangkat yang menjalankan Android 11 dan yang lebih tinggi, LPA dapat memulai UI aplikasi operator. Hal ini berguna karena aplikasi operator mungkin memerlukan informasi tambahan dari pengguna sebelum memberikan kode aktivasi ke LPA. Misalnya, operator mungkin mewajibkan pengguna login untuk mengaktifkan nomor telepon mereka atau melakukan layanan transfer nomor lainnya.
Berikut adalah proses untuk memulai UI aplikasi operator di LPA:
LPA meluncurkan alur aktivasi aplikasi operator dengan mengirimkan intent
android.service.euicc.action.START_CARRIER_ACTIVATIONke paket aplikasi operator yang berisi tindakan. (Penerima aplikasi operator harus dilindungi dalam deklarasi manifes denganandroid:permission="android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS"untuk menghindari penerimaan intent dari aplikasi non-LPA.)String packageName = // The carrier app's package name Intent carrierAppIntent = new Intent(“android.service.euicc.action.START_CARRIER_ACTIVATION”) .setPackage(packageName); ResolveInfo activity = context.getPackageManager().resolveActivity(carrierAppIntent, 0); carrierAppIntent .setClassName(activity.activityInfo.packageName, activity.activityInfo.name); startActivityForResult(carrierAppIntent, requestCode);Aplikasi operator melakukan tugasnya menggunakan UI-nya sendiri. Misalnya, login pengguna atau mengirim permintaan HTTP ke backend operator.
Aplikasi operator merespons LPA dengan memanggil
setResult(int, Intent)danfinish().- Jika aplikasi operator merespons dengan
RESULT_OK, LPA akan melanjutkan alur aktivasi. Jika aplikasi operator menentukan bahwa pengguna harus memindai kode QR, bukan mengizinkan LPA mengikat layanan aplikasi operator, aplikasi operator merespons LPA menggunakansetResult(int, Intent)denganRESULT_OKdan instanceIntentyang berisi ekstra booleanandroid.telephony.euicc.extra.USE_QR_SCANNERyang ditetapkan ketrue. LPA kemudian memeriksa ekstra dan meluncurkan pemindai QR, bukan mengikat penerapanICarrierEuiccProvisioningServiceaplikasi operator. - Jika aplikasi operator error atau merespons dengan
RESULT_CANCELED(ini adalah kode respons default), LPA akan membatalkan alur aktivasi eSIM. - Jika aplikasi operator merespons dengan sesuatu selain
RESULT_OKatauRESULT_CANCELED, LPA akan memperlakukannya sebagai error.
Untuk alasan keamanan, LPA tidak boleh langsung menerima kode aktivasi yang diberikan dalam intent hasil untuk memastikan bahwa pemanggil non-LPA tidak dapat memperoleh kode aktivasi dari aplikasi operator.
- Jika aplikasi operator merespons dengan
Meluncurkan alur aktivasi LPA di aplikasi operator
Mulai Android 11, aplikasi operator dapat menggunakan eUICC API untuk memulai LUI untuk aktivasi eSIM. Metode ini menampilkan UI alur aktivasi eSIM LPA untuk mengaktifkan profil eSIM. Kemudian, LPA mengirimkan siaran saat aktivasi profil eSIM selesai.
LPA harus mendeklarasikan aktivitas yang menyertakan filter intent dengan tindakan
android.service.euicc.action.START_EUICC_ACTIVATION. Prioritas filter intent harus ditetapkan ke nilai bukan nol jika ada beberapa implementasi di perangkat. Contoh:<application> ... <activity android:name=".CarrierAppInitActivity" android:exported="true"> <intent-filter android:priority="100"> <action android:name="android.service.euicc.action.START_EUICC_ACTIVATION" /> </intent-filter> </activity> ... </application>Aplikasi operator melakukan tugasnya menggunakan UI-nya sendiri. Misalnya, login pengguna atau mengirim permintaan HTTP ke backend operator.
Pada tahap ini, aplikasi operator harus siap menyediakan kode aktivasi melalui penerapan
ICarrierEuiccProvisioningService-nya. Aplikasi operator meluncurkan LPA dengan memanggilstartActivityForResult(Intent, int)dengan tindakanandroid.telephony.euicc.action.START_EUICC_ACTIVATION. LPA juga memeriksa ekstra booleanandroid.telephony.euicc.extra.USE_QR_SCANNER. Jika nilainya adalahtrue, LPA meluncurkan pemindai QR agar pengguna dapat memindai kode QR profil.Di sisi LPA, LPA terikat ke penerapan
ICarrierEuiccProvisioningServiceaplikasi operator untuk mengambil kode aktivasi dan mendownload profil yang sesuai. LPA menampilkan semua elemen UI yang diperlukan selama proses download, seperti layar pemuatan.Setelah alur aktivasi LPA selesai, LPA akan merespons aplikasi operator dengan kode hasil, yang ditangani aplikasi operator di
onActivityResult(int, int, Intent).- Jika LPA berhasil mendownload profil eSIM baru, LPA akan merespons dengan
RESULT_OK. - Jika pengguna membatalkan aktivasi profil eSIM di LPA, LPA akan merespons dengan
RESULT_CANCELED. - Jika LPA merespons dengan sesuatu selain
RESULT_OKatauRESULT_CANCELED, aplikasi operator akan memperlakukan hal ini sebagai error.
Untuk alasan keamanan, LPA tidak menerima kode aktivasi secara langsung di intent yang diberikan untuk memastikan bahwa pemanggil non-LPA tidak dapat mendapatkan kode aktivasi dari aplikasi operator.
- Jika LPA berhasil mendownload profil eSIM baru, LPA akan merespons dengan
Mendukung beberapa eSIM
Untuk perangkat yang menjalankan Android 10 atau yang lebih tinggi, class
EuiccManager mendukung perangkat
dengan beberapa eSIM. Perangkat dengan satu eSIM yang diupgrade ke
Android 10
tidak memerlukan modifikasi apa pun pada penerapan LPA karena platform
secara otomatis mengaitkan instance EuiccManager dengan eUICC default. eUICC
default ditentukan oleh platform untuk perangkat dengan HAL radio versi 1.2 atau yang lebih tinggi dan oleh LPA untuk perangkat dengan HAL radio versi yang lebih rendah dari 1.2.
Persyaratan
Untuk mendukung beberapa eSIM, perangkat harus memiliki lebih dari satu eUICC, yang dapat berupa eUICC bawaan atau slot SIM fisik tempat eUICC yang dapat dilepas dapat dimasukkan.
Radio HAL versi 1.2 atau yang lebih tinggi diperlukan untuk mendukung beberapa eSIM. Radio HAL versi 1.4 dan RadioConfig HAL versi 1.2 direkomendasikan.
Implementasi
Untuk mendukung beberapa eSIM (termasuk eUICC yang dapat dilepas atau SIM yang dapat diprogram), LPA harus menerapkan
EuiccService,
yang menerima ID slot yang sesuai dengan ID kartu yang diberikan pemanggil.
Resource
non_removable_euicc_slots
yang ditentukan dalam
arrays.xml
adalah array bilangan bulat yang merepresentasikan ID slot eUICC bawaan
perangkat. Anda harus menentukan resource ini agar platform dapat menentukan apakah eUICC yang dimasukkan dapat dilepas atau tidak.
Aplikasi operator untuk perangkat dengan beberapa eSIM
Saat membuat aplikasi operator untuk perangkat dengan beberapa eSIM, gunakan metode
createForCardId
di EuiccManager untuk membuat objek EuiccManager yang disematkan ke
ID kartu tertentu. ID kartu adalah nilai bilangan bulat yang secara unik mengidentifikasi UICC
atau eUICC di perangkat.
Untuk mendapatkan ID kartu untuk eUICC default perangkat, gunakan metode
getCardIdForDefaultEuicc
di TelephonyManager. Metode ini menampilkan
UNSUPPORTED_CARD_ID
jika versi HAL radio lebih rendah dari 1.2 dan menampilkan
UNINITIALIZED_CARD_ID
jika perangkat belum membaca eUICC.
Anda juga bisa mendapatkan ID kartu dari
getUiccCardsInfo
dan getUiccSlotsInfo (API sistem) di TelephonyManager, serta
getCardId
di SubscriptionInfo.
Saat objek EuiccManager telah dibuat instance-nya dengan ID kartu tertentu, semua
operasi diarahkan ke eUICC dengan ID kartu tersebut. Jika eUICC tidak dapat dijangkau (misalnya, saat dinonaktifkan atau dilepas), EuiccManager tidak akan berfungsi lagi.
Anda dapat menggunakan contoh kode berikut untuk membuat aplikasi operator.
Contoh 1: Dapatkan langganan aktif dan buat instance EuiccManager
// Get the active subscription and instantiate an EuiccManager for the eUICC which holds
// that subscription
SubscriptionManager subMan = (SubscriptionManager)
mContext.getSystemService(Context.TELEPHONY_SUBSCRIPTION_SERVICE);
int cardId = subMan.getActiveSubscriptionInfo().getCardId();
EuiccManager euiccMan = (EuiccManager) mContext.getSystemService(Context.EUICC_SERVICE)
.createForCardId(cardId);
Contoh 2: Lakukan iterasi melalui UICC dan buat instance EuiccManager untuk eUICC yang dapat dilepas
// On a device with a built-in eUICC and a removable eUICC, iterate through the UICC cards
// to instantiate an EuiccManager associated with a removable eUICC
TelephonyManager telMan = (TelephonyManager)
mContext.getSystemService(Context.TELEPHONY_SERVICE);
List<UiccCardInfo> infos = telMan.getUiccCardsInfo();
int removableCardId = -1; // valid cardIds are 0 or greater
for (UiccCardInfo info : infos) {
if (info.isRemovable()) {
removableCardId = info.getCardId();
break;
}
}
if (removableCardId != -1) {
EuiccManager euiccMan = (EuiccManager) mContext.getSystemService(Context.EUICC_SERVICE)
.createForCardId(removableCardId);
}
Validasi
AOSP tidak dilengkapi dengan penerapan LPA dan Anda tidak diharapkan memiliki LPA yang tersedia di semua build Android (tidak semua ponsel mendukung eSIM). Oleh karena itu, tidak ada kasus pengujian CTS end-to-end. Namun, kasus pengujian dasar tersedia di AOSP untuk memastikan bahwa API eUICC yang diekspos valid dalam build Android.
Anda harus memastikan build lulus kasus pengujian CTS berikut (untuk API publik): /platform/cts/tests/tests/telephony/current/src/android/telephony/euicc/cts.
Operator yang menerapkan aplikasi operator harus melalui siklus penjaminan kualitas internal normal untuk memastikan semua fitur yang diterapkan berfungsi seperti yang diharapkan. Setidaknya, aplikasi operator harus dapat mencantumkan semua profil langganan yang dimiliki oleh operator yang sama, mendownload dan menginstal profil, mengaktifkan layanan di profil, beralih antar-profil, dan menghapus profil.
Jika Anda membuat LPA sendiri, Anda harus melakukan pengujian yang jauh lebih ketat. Anda harus bekerja sama dengan vendor modem, vendor chip eUICC atau OS eSIM, vendor SM-DP+, dan operator untuk menyelesaikan masalah dan memastikan interoperabilitas LPA Anda dalam arsitektur RSP. Sejumlah pengujian manual yang baik tidak dapat dihindari. Untuk cakupan pengujian terbaik, Anda harus mengikuti Rencana Pengujian RSP SGP.23 GSMA.