Funkcionalnost eSIM v Flutter-ju

Eden naših zadnjih projektov je bila aplikacija za predplačniške mobilne pakete za enega največjih slovenskih ponudnikov telekomunikacijskih storitev. Odločili smo se za uporabo Flutter-ja, ogrodja za več platform, ki omogoča eno samo kodo za več operacijskih sistemov, v tem primeru Android in iOS.

Eden glavnih izzivov pri ustvarjanju aplikacije je bila funkcionalnost za namestitev eSIM neposredno iz aplikacije, brez uporabe kode QR ali zunanjih metod. V tem članku bomo delili naša spoznanja in razložili, kako nam je uspelo to implementirati za Android in iOS.

Funkcionalnost eSIM

Vmesniki za dodajanje eSIM-ov v napravo so na obeh operacijskih sistemih zaklenjeni in potrebujejo posebna dovoljenja ter upravičenja, vendar resnično ni tako težko, ko vas enkrat usmerijo v pravo smer.

Profil eSIM

Profil eSIM, ki ga dobite od ponudnika eSIM, je običajno videti takole:

LPA:1$prod.smdp-plus.rsp.goog$052X-UFXS-CQIY-PNGL

To je primer s spletne strani https://source.android.com/docs/core/connect/esim-test-profiles. Profil je sestavljen iz dveh delov, naslova (prod.smdp-plus.rsp.goog) in ujemajočega se ID-ja (052X-UFXS-CQIY-PNGL).

Android

Android ima več načinov za dodajanje eSIM-a neposredno iz aplikacije, vendar nekateri delujejo le na določenih napravah:

1. Uporaba lokalne aplikacije pomočnika za profile (LPA)
2. Uporaba aktivacijske kode eSIM kot namere (intent)
3. Uporaba EuiccManagerja

Vse so podrobneje opisane tukaj: https://source.android.com/docs/core/connect/esim-overview, mi pa bomo podali kratek pregled v naslednjih razdelkih.

Uporaba lokalne aplikacije pomočnika za profile (LPA)

Ta način ne zahteva nobenih posebnih dovoljenj ali sprememb metapodatkov profila eSIM. Ta potek smo uspešno implementirali, vendar izgleda, da deluje samo na napravah Samsung (morda tudi na nekaterih drugih, vendar so bili telefoni Samsung edini med testiranimi napravami, ki so dejansko delovali). Ta implementacija je močno odvisna od implementacije LPA (Local Profile Assistant) proizvajalca, saj je LPA sistemska aplikacija.

Naša implementacija sledi dokumentaciji, ki je na voljo tukaj: https://source.android.com/docs/core/connect/esim-overview#activation-code.

Uporaba aktivacijske kode eSIM kot namere (intent)

To je precej preprost pristop, vendar očitno deluje samo na telefonih Pixel ali morda na telefonih, ki so dovolj blizu AOSP (čista izvorna koda Androida). Tudi ta ne zahteva nobenih posebnih dovoljenj ali sprememb metapodatkov profila eSIM. Implementacija je naslednja:

val lpa = "LPA:1$..."

val intent = Intent(Intent.ACTION_VIEW)

intent.data  = Uri.parse(lpa)
intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK

startActivity(intent)

Kot lahko vidite, preprosto ustvarimo novo namero, nastavimo aktivacijsko kodo eSIM kot podatke in smo zaključili. Sistem odpre nastavitve za aktivacijo eSIM-a in od tam lahko nadaljujemo.

Uporaba EuiccManagerja

Prejšnja dva pristopa ne zahtevata posebnih dovoljenj, vendar ne delujeta na vseh napravah in tudi ne zagotavljata nobenih informacij o tem, ali je bila kartica eSIM uspešno dodana. Tu torej nastopi zadnji pristop.

EuiccManager je standardni način implementacije funkcionalnosti eSIM v aplikaciji, saj deluje na vseh napravah Android, ki uporabljajo Android 9 ali novejšega, vendar zahteva privilegije operaterja, kar pa pomeni dodatne spremembe s strani vašega operaterja oziroma ponudnika eSIM.

Postopek je naslednji:

1. Podpišete AAB ali APK s svojim ključem, naj bo to razvojni ali produkcijski ključ, in dobite podpis SHA-256.
2. Pridobite ime paketa svoje aplikacije.
3. Operater/ponudnik eSIM mora dodati tri stvari v metapodatke profila eSIM (za več podrobnosti si preberite tukaj: https://source.android.com/docs/core/connect/uicc#rules_on_uicc):
   1. DeviceAppID-REF-DO: To je SHA-256 podpis vaše aplikacije.
   2. PKG-REF-DO: To je ime paketa vaše aplikacije.
   3. PERM-AR-DO: To je 8-bajtna maska, ki predstavlja 64 ločenih dovoljenj.
      • OPOMBA: Trenutno se to ne uporablja, vendar je tam za prihodnjo uporabo, kot je zapisano v dokumentaciji. Nastavite jo na katero koli vrednost, na primer 0000000000000001.
4. Ko operater/ponudnik eSIM doda te vrednosti v metapodatke profila eSIM, lahko začnete uporabljati API EuiccManager.
5. Pri poskusu dodajanja/posodabljanja/odstranjevanja naročnine eSIM bo Android preveril, ali se podpis SHA-256 in ime paketa ujemata s podpisom in imenom paketa aplikacije. Če je to res, imate zdaj privilegij operaterja nad profilom eSIM.

Dokumentacija Androida o eSIM je precej dobra, zato preprosto sledite korakom, opisanim tukaj, da jo implementirate v svojo aplikacijo: https://source.android.com/docs/core/connect/esim-overview#euicc-manager.

iOS

Na iOS-u imate dva načina za dodajanje eSIM-a iz vaše aplikacije:

1. Uporaba univerzalne povezave Apple za eSIM
2. Uporaba integriranih metod za namestitev profila eSIM

Uporaba univerzalne povezave Apple za eSIM

To je najlažji način za dodajanje eSIM-a na iOS-u, preprosto dodate svojo aktivacijsko kodo v ta URL namesto {LPA_TOKEN} https://esimsetup.apple.com/esim_qrcode_provisioning?carddata={LPA_TOKEN} in odprete URL. Sistem bo razčlenil odgovor in odprl sistemske nastavitve za dodajanje eSIM-a. In to je to, končali ste.

Slaba stran pa je, da ne dobite nobenih povratnih klicev, ali je bila kartica eSIM uspešno dodana ali ne, in tudi, da ste preusmerjeni iz svoje aplikacije, ko se odprejo nastavitve.

Uporaba integriranih metod za namestitev profila eSIM

Za upravljanje kartic eSIM neposredno na iOS-u z uporabo integriranih metod potrebujete tako imenovano upravičenje za eSIM (eSIM entitlement), ki je povezano z vašim profilom. Za pridobitev upravičenja se morate neposredno obrniti na prodajnega predstavnika Appla in mu razložiti svoj primer uporabe. Apple nato pregleda vašo aplikacijo in odobri ali zavrne upravičenje za eSIM. To lahko traja od enega tedna do več mesecev (kot smo prebrali na nekaterih forumih). Imeli smo srečo, ker nam je Apple odgovoril v manj kot dveh tednih, vendar je šlo za zelo velikega ponudnika telekomunikacijskih storitev, ki je imel že vso potrebno infrastrukturo in procese za upravljanje s karticamieSIM.

Ko imate nastavljeno upravičenje za eSIM, lahko začnete uporabljati razred CTCellularPlanProvisioning, ki je v ogrodju Core Telephony. Implementacija je precej preprosta:

let ctcp = CTCellularPlanProvisioning()

func installEsimProfile(address: String, matchingID: String, completion: @escaping (String) -> Void) {
  let ctpr = CTCellularPlanProvisioningRequest();

  ctpr.address = address;
  ctpr.matchingID = matchingID;

  if #available(iOS 12.0, *) {
    ctcp.addPlan(with: ctpr) { (result) in
      switch result {
      case .unknown:
        completion("unknown")
      case .fail:
        completion("error")
      case .success:
        completion("success")
      case .cancel:
        completion("error")
      @unknown default:
        completion("unknown")
      }
    }
  } else {
    completion("error")
  }
}

Če je bila kartica eSIM uspešno dodana, dobite odgovor success in to je to.

Zaključek

Upamo, da vam je ta kratek članek pomagal pri implementaciji vaše lastne aplikacije za upravljanje s karticami eSIM. Je nekoliko okorno in zamudno ter dokumentacija včasih ni najbolj jasna, vendar boste na koncu prišli do cilja.