18

After searching everywhere I found there is a way to add eSIM in iPhone using the following API 

func addPlan(with: CTCellularPlanProvisioningRequest, completionHandler: (CTCellularPlanProvisioningAddPlanResult) -> Void)

I don't know why but completion handler not returning the result of CTCellularPlanProvisioningAddPlanResult just printing the following error.

Domain=NSCocoaErrorDomain Code=4099 "The connection to service named
com.apple.commcenter.coretelephony.xpc was invalidated." UserInfo=
{NSDebugDescription=The connection to service named
com.apple.commcenter.coretelephony.xpc was invalidated.

I want to know how this API works, You can see my code below

let ctpr = CTCellularPlanProvisioningRequest()
ctpr.address = "SMDP+"
ctpr.confirmationCode = ""
ctpr.eid = ""
ctpr.iccid = ""

let ctcp =  CTCellularPlanProvisioning()
ctcp.addPlan(with: ctpr) { (result) in
    print(result)
}

I am using CoreTelephony framework

Any help would be appricated

After checking other apps I found that GigSky is doing the same, anyone knows how they are doing?

UPDATE:

As of now I found the entitlement request URL check below

https://developer.apple.com//contact/request/esim-access-entitlement

I requested but apple is not responding.

Nick
  • 1,127
  • 2
  • 15
  • 40
  • E-sim's are only available in iPhone XR, iPhone Xs, and Xs Max models. Theres an actual physical esim inside those devices. Also not all carriers support esims, you cant just load whatever carrier you want in there. – AlexM Dec 12 '18 at 12:42
  • Thanks for the reply. I know eSIM's are available only for the selected device with iOS >12 and the carrier should support it. I do have an actual eSIM and latest device and I know how to link eSIM manually by going in setting and add cellular data plan then scan the QR code but I want to automate this process so that user no need to scan the code manually. I do believe that addPlan function can do this and can create eSIM profile. – Nick Dec 13 '18 at 02:23
  • One problem i think you are going to have, is that you cant get the IMEI programatically. Apple doesn't allow this because you can use it to track users uniquely. So thats a step the user will have to do himself. How do you get the object CTCellularPlanProvisioningRequest? – AlexM Dec 13 '18 at 10:49
  • I am creating CTCellularPlanProvisioningRequest object and passing the data which I am getting from eSIM. – Nick Dec 13 '18 at 10:58
  • Aren't you supposed to get this data from the carrier after you register a plan? I think thats what the QRCode scan is for. – AlexM Dec 13 '18 at 11:19
  • so why addPlan function is having CTCellularPlanProvisioningRequest object as an argument. What does this function do? – Nick Dec 14 '18 at 02:26
  • I think it loads the plan in to the eSIM on the device. Thats possibly why the QRScan is needed, so the app can retrieve the relevant data and load the plan in the eSIM like you would do if you typed it manually in the settings. – AlexM Dec 14 '18 at 12:56
  • What is that QR code contains? I think It's basically the profile details which I am passing using CTCellularPlanProvisioningRequest object. So I am just trying to call this function so that user can purchase the eSIM online and without any user interaction app can handle this for the user. – Nick Dec 15 '18 at 09:33
  • The QR code just contains the 2 or 3 fields on the next screen that you see if you tap "Enter Details Manually". That is, "SM-DP+ Address" and "Activation Code" (and possibly, "Confirmation Code"). The OS handles things from there. So the QR Code is just to prevent the user having to enter those codes manually. – Mason Feb 01 '19 at 04:03
  • I have the esim profile indeed the supportsCellularPlan() method return true, but when call the addPlan method, i receive the same error "code=4099". Do you have any new or info? – fbenedet Feb 18 '19 at 14:02
  • @fbenedet Not yet. – Nick Feb 19 '19 at 02:46
  • @fbenedet What did you do to get supportsCellularPlan() return true? I have the entitlements as well but it always returns false! I opened a new question about this, maybe you could help me out? https://stackoverflow.com/questions/58630606/coretelephony-esim-functions-not-working-on-device – Thomas Oct 31 '19 at 12:45
  • How to get eSIM EID using code, Can someone help me on this. – naresh kolindala Nov 02 '20 at 04:56
  • check this https://developer.apple.com/documentation/coretelephony/ctcellularplanprovisioningrequest/2981845-eid – Nick Nov 02 '20 at 05:52

2 Answers2

14

With this process, you can integrate eSIM functionality into your iOS app.

Step 1

Request for eSIM entitlement using your developer account Request from here

Step 2

Apple will approve the entitlement after some time (For me it took months) You can check if Apple has approved the entitlement from your app profile setting App profile setting (Certificate manager)

Step 3

Download the App Dev and Distribution profile (By selecting eSIM entitlement as Step #2).

Step 4

Update your info.plist with below keys and value

<key>CarrierDescriptors</key>

<array>
     <dict>
     <key>MCC</key> //Mobile country code
         <string>’mnc value’</string>
     <key>MNC</key> // Mobile network code
         <string>’mnc value’</string>
     </dict>
</array>
<key>com.apple.security.network.server</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.CommCenter.fine-grained</key>
<array>
    <string>spi</string>
    <string>sim-authentication</string>
    <string>identity</string>
</array>
<key>com.apple.wlan.authentication</key>
<true/>
<key>keychain-access-groups</key>
<array>
    <string>apple</string>
    <string>com.apple.identities</string>
    <string>com.apple.certificates</string>
</array>
<key>com.apple.private.system-keychain</key>
<true/>

Step 5 (Could be optional)

Update your {appname}.entitlements with below key and value

<key>com.apple.CommCenter.fine-grained</key>
<array>
    <string>public-cellular-plan</string>
</array>

Step 6 Code to Add eSIM profile

 let ctpr = CTCellularPlanProvisioningRequest()
 ctpr.address = "Your eSIM profile address"
 ctpr.matchingID = "Confirmation id"

 if #available(iOS 12.0, *) {
        let ctcp =  CTCellularPlanProvisioning()
        ctcp.addPlan(with: ctpr) { (result) in
            switch result {
            case .unknown:
                self.showGenericSingleButtonCustomAlert(description: "Sorry unknown error")
            case .fail:
                self.showGenericSingleButtonCustomAlert(description: "Oops! something went wrong")
            case .success:
                self.showGenericSingleButtonCustomAlert(description: "Yay! eSIM installed successfully")
            @unknown default:
                self.showGenericSingleButtonCustomAlert(description: "Oops! something went wrong")
            }
        }
    }
FreeGor
  • 615
  • 13
  • 26
Nick
  • 1,127
  • 2
  • 15
  • 40
  • >> (For me it took months) More than 3 months? We are still waiting, +2 months and still not approved. – Ibrahim Al Mahfooz Feb 15 '20 at 09:03
  • Hey @IbrahimAl-Mahfooz, I can understand the pain with getting approval. Actually, they don't have any specific guidelines but I would suggest talking to Apple technical support. – Nick Feb 17 '20 at 02:14
  • Update your developer and distribution profile in Xcode by enabling eSIM entitlement in it. For this step 3 what we need to do in Xcode. Please explain in detail @Nick – naresh kolindala Apr 30 '20 at 13:33
  • 1
    Ohh Yea, You have to update your profile with new profile in Xcode. – Nick Apr 30 '20 at 13:49
  • supportsCellularPlan is always getting false. After following all the above steps @Nick – naresh kolindala Jun 18 '20 at 06:58
  • let provisioning = CTCellularPlanProvisioning() let supportsESIM = provisioning.supportsCellularPlan() The above code is added to check eSIM is available or not in iPhone devices, Currently i am checking in iPhone XS Max Device. – naresh kolindala Jun 18 '20 at 07:41
  • 1
    - @nareshkolindala, Here you have to make sure whether you have the APIs approved by apple also try adding permission in the info PList, I am not sure which one to add. – Nick Nov 02 '20 at 05:51
  • @Nick How to get EID of device. Can you please share me the code to fetch EID number. – naresh kolindala Nov 02 '20 at 06:07
  • -@nareshkolindala, https://developer.apple.com/documentation/coretelephony/ctcellularplanprovisioningrequest/2981845-eid, Remember you need to have permission to read-only your esim profiles – Nick Nov 02 '20 at 06:32
  • @Nick when we are using ad-hoc profile is showing ineligible how to resolve this issue. – naresh kolindala Nov 10 '20 at 14:37
  • Nice!, very useful information and well drafted – Narayana Rao Routhu Feb 15 '22 at 12:08
  • 1
    Thanks @Narayana – Nick Feb 16 '22 at 05:10
  • Hi @Nick for installing as mentioned we need address and matchingID. can you please explain what these values actually? – Narayana Rao Routhu Apr 19 '22 at 11:26
  • These you should be getting from eSIM profile, each eSIM Profile should have its address and sim properties – Nick Apr 19 '22 at 20:41
  • 1
    Hi @Nick we need to add CarrierDescriptors also to work so i have edited your answer please check approve that – Narayana Rao Routhu Apr 29 '22 at 15:02
  • Has anyone found any alternative ways to load an eSim onto a device without relying on Apple to provide approval, making the user scan a QR code or worse making the user enter it manually. I saw there is a way via iMessage but haven’t found any information on how to implement it. Is there not a way via a url, schema or download? – Craig P Mar 24 '23 at 01:10
4

This API is only available for carriers. You need a special entitlement from Apple to be able to call it in your application, otherwise you will get the error you mentioned.

Just to clarify something about eSIMs; there are several ways to add eSIM to the device:

  • the simplest way that most carriers are implementing now is through scanning a QR code from the device settings, which does not require any development work on the carrier's app.
  • The other way is to install the eSIM profile using the carrier app, which can only be done with a special entitlement that is provided by Apple. The entitlement allows you to call CTCellularPlanProvisioning.addPlan(with: ) API that you referred to you in your question
Krimboss
  • 41
  • 1
  • 2
  • How to add that entitlement? – Nick Dec 17 '18 at 10:16
  • You need to submit a request for that entitlement to Apple through the developer portal, which will be reviewed and manually approved. – Krimboss Dec 17 '18 at 10:55
  • 1
    Can you tell me the name of that entitlement? – Nick Dec 19 '18 at 09:43
  • But the absurd thing about supporting **only** a QR code to do this work is that you cannot complete everything on the iOS device... you need to either print the QR code out on paper (yeah right) or send it to another device to take a picture of the QR code on the screen. AFAICT (and I would **love** to be wrong, please tell me if I am), there is therefore no way to implement buying and activatig an eSIM plan using only the iOS device, other than making the user manually input those details. :-/ – Mason Feb 01 '19 at 04:51
  • Hey @Mason, I found GigSky is allowing users to purchase and activate eSIM using there own app. You can check that. – Nick Feb 08 '19 at 03:33
  • @Nick Right, I tried their app and bought a 1-day data eSIM plan to see how it worked. GigSky apparently does have the entitlement described above, though, so their app is able to use the restricted `addPlan()’ API. (Like you, I also applied for the entitlement but have not gotten a response from Apple...) – Mason Feb 09 '19 at 04:13
  • @Mason I really don't know what is wrong with apple, I tried sending multiple requests. – Nick Feb 11 '19 at 02:07
  • @Nick It is bit tedious process to get entitlement, you need to be MNO and owning towers, along with that you need to do some contracts with Apple to enable this esim APIs for you. – Vatsal K May 07 '19 at 15:41
  • @VatsalK If one gets the entitlement, can you install esims for other networks as well or just for the one you signed on for? – Muhammad Zaid Ikhlas Sep 18 '19 at 20:47
  • Hi @Krimboss, it seems like you know the drill for the eSIM implementation using mobile app instead of physical QR code. We are MNO and currently working on eSIM project and would like to build a mobile app like GigSky App which allow our customers to download the eSIM profile directly into their mobile device. We already submitted our entitlement request to Apple but still no response from them. Do we need an entitlement in order to use the LPA API to download the eSIM profile from the SM-DP+? or it is possible to use the API directly? We are a bit confused. Appreciate your help. – Ibrahim Al Mahfooz Dec 17 '19 at 06:46
  • 1
    @IbrahimAl-Mahfooz You need to speak to your Apple sales rep first. You must be entitled to use this restricted API. It as assumed you already have a process to perform ES2+ DownloadOrder, ConfirmOrder and (potentially) ReleaseProfile on the SM-DP+. Depending on your operator setup, you may choose to "Link" an eSIM to an EID (in which case, no MatchingID would be generated), or use "Allocate" an eSIM, and use the MatchingID to add the plan with. Hope this helps. -Hussam – h q Feb 09 '20 at 09:49
  • Thank you for the reply. Well, we applied for Apple entitlement since 2 months and still no response from them. We also contacted them many times, without any helpful information about time estimated to get our request approved to use the API. Perhaps you came across the entitlement request process, any idea how long will it take for Apple to respond to similar requests? – Ibrahim Al Mahfooz Feb 15 '20 at 08:44
  • @IbrahimAl-Mahfooz Did you get approve from Apple? How long had you been waiting? – krbiz Feb 08 '21 at 14:42
  • No. It is like a black hole. Send a request and forget about it. I contacted them more than five times, they keep saying that they don't have any estimated time. – Ibrahim Al Mahfooz Feb 09 '21 at 16:55
  • Has anyone found any alternative ways to load an eSim onto a device without relying on Apple to provide approval, making the user scan a QR code or worse making the user enter it manually. I saw there is a way via iMessage but haven’t found any information on how to implement it. Is there not a way via a url, schema or download? – Craig P Mar 23 '23 at 20:59