Dashboard

How to Integrate eSIM Functionality into Your iOS App

Apple In App Provisioning

Who Can Use the Apple eSIM API?

Apple provides several ways to add an eSIM to a device. The most straightforward method, widely implemented by carriers, involves scanning a QR code from the device settings. This method does not require any development work on the carrier’s app, making it accessible and easy to use for most carriers.

However, there is a more integrated method to install the eSIM profile using a carrier app. This method requires a special entitlement provided by Apple. This entitlement enables the use of the CTCellularPlanProvisioning.addPlan(with:) API, which allows the app to provision eSIM profiles directly onto the device.

To use this API, the carrier must meet specific criteria:

  • Mobile Network Operator (MNO): The carrier must be an MNO, which means they own and operate the network towers.
  • Contract with Apple: The carrier must enter into specific agreements with Apple to enable the eSIM APIs.

Steps to Enable eSIM APIs

  1. Contact Apple Sales Representative: The carrier must first discuss with their Apple sales representative to gain access to the restricted API.
  2. Obtain Entitlement: Apple provides the necessary entitlement after confirming the carrier’s eligibility and agreements.
  3. Technical Requirements: The carrier should already have processes in place for ES2+ operations such as DownloadOrder, ConfirmOrder, and potentially ReleaseProfile on the SM-DP+ (Subscription Manager Data Preparation +).

Integration Options

Depending on the carrier’s setup, they may choose one of the following methods to link an eSIM to a device:

  • Linking an eSIM to an EID: This method does not generate a MatchingID.
  • Allocating an eSIM: This method uses a MatchingID to add the plan with the API.

These steps ensure that only qualified and properly equipped carriers can use the advanced eSIM provisioning features, maintaining the security and reliability of the eSIM ecosystem.

Overview of CTCellularPlanProvisioning.addPlan(with:)

The CTCellularPlanProvisioning.addPlan(with:) API is part of the CoreTelephony framework. It enables carrier apps to provision a cellular plan directly onto an eSIM-enabled device without the user needing to manually enter plan details or scan a QR code.

Capabilities of addPlan(with:)

  1. Automatic eSIM Profile Installation
    • The primary function of this API is to install an eSIM profile onto the device. The profile contains all the necessary settings for the device to connect to the carrier’s network, including the carrier’s network information, authentication credentials, and any specific configuration needed for the service.
  2. Streamlined User Experience
    • By using this API, carriers can provide a seamless and integrated user experience within their app. Users can simply select or purchase a cellular plan within the carrier’s app, and the app can then automatically configure the eSIM without requiring additional user input or actions.
  3. Enhanced Security and Reliability
    • The API ensures that the provisioning process is secure, adhering to Apple’s stringent security guidelines. Only authorized apps with the necessary entitlement can use this API, ensuring that only trusted carriers can provision eSIM profiles.
  4. Integration with Carrier Systems
    • The API allows for deep integration with carrier backend systems. Carriers can implement processes to manage eSIM profiles, such as allocating a profile to a user, linking it to the device’s EID (Embedded Identity Document), and handling the necessary authentication and network setup automatically.

Technical Process

When using the CTCellularPlanProvisioning.addPlan(with:) API, the following steps are typically involved:

  1. Prepare the eSIM Activation Request
    • The carrier app prepares an activation request containing the eSIM profile details. This includes the necessary network information, credentials, and any additional settings required for the cellular plan.
  2. Call the API
    • The carrier app calls the CTCellularPlanProvisioning.addPlan(with:) method, passing in the prepared activation request. This triggers the provisioning process on the device.
  3. Handle the Response
    • The API returns a result indicating whether the provisioning was successful or if there were any errors. The app can then handle these responses accordingly, providing feedback to the user or taking corrective actions if necessary.

info.plist File

				
					<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleName</key>
    <string>YourAppName</string>
    <key>CFBundleIdentifier</key>
    <string>com.yourcompany.yourapp</string>
    <key>CFBundleVersion</key>
    <string>1.0</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
    <key>CFBundleExecutable</key>
    <string>${EXECUTABLE_NAME}</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>LSRequiresIPhoneOS</key>
    <true/>
    <key>UILaunchStoryboardName</key>
    <string>LaunchScreen</string>
    <key>UIRequiredDeviceCapabilities</key>
    <array>
        <string>armv7</string>
    </array>
    <key>UIStatusBarStyle</key>
    <string>UIStatusBarStyleDefault</string>
    <key>UISupportedInterfaceOrientations</key>
    <array>
        <string>UIInterfaceOrientationPortrait</string>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
    <key>UISupportedInterfaceOrientations~ipad</key>
    <array>
        <string>UIInterfaceOrientationPortrait</string>
        <string>UIInterfaceOrientationPortraitUpsideDown</string>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
    <key>CarrierDescriptors</key>
    <array>
        <dict>
            <key>MNC</key>
            <string>03</string>
            <key>MCC</key>
            <string>260</string>
            <key>GID1</key>
            <string>ffffffffffffffffffff</string>
            <key>GID2</key>
            <string>ffffffffffffffffffff</string>
        </dict>
    </array>
    <key>UIBackgroundModes</key>
    <array>
        <string>fetch</string>
        <string>remote-notification</string>
    </array>
    <key>NSCameraUsageDescription</key>
    <string>$(PRODUCT_NAME) needs access to the camera to take photos.</string>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>$(PRODUCT_NAME) needs access to your location to show relevant content.</string>
    <key>NSLocationAlwaysUsageDescription</key>
    <string>$(PRODUCT_NAME) needs access to your location to show relevant content.</string>
    <key>UIBackgroundModes</key>
    <array>
        <string>fetch</string>
        <string>remote-notification</string>
    </array>
</dict>
</plist>

Explanation of the info.plist File

  1. Basic App Information
    • CFBundleName: The name of your app.
    • CFBundleIdentifier: The unique identifier for your app.
    • CFBundleVersion and CFBundleShortVersionString: Version numbers for your app.
  2. Device and Orientation Configurations
    • CFBundleDevelopmentRegion: Default language for your app.
    • CFBundleExecutable and CFBundlePackageType: Specifies that this is an app package.
    • LSRequiresIPhoneOS: Indicates that the app requires iPhone OS.
    • UIRequiredDeviceCapabilities: Lists required device capabilities (e.g., armv7).
    • UIStatusBarStyle: Status bar appearance.
    • UISupportedInterfaceOrientations: Supported interface orientations.
  3. eSIM Carrier Descriptors
    • CarrierDescriptors: An array of dictionaries, each containing:
      • MNC: Mobile Network Code.
      • MCC: Mobile Country Code.
      • GID1 and GID2: Group Identifiers (optional).
  4. Background Modes
    • UIBackgroundModes: Lists the background modes your app supports (e.g., fetch and remote-notification).
  5. Privacy Descriptions
    • NSCameraUsageDescription: Describes why your app needs camera access.
    • NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription: Describe why your app needs location access.

Customizing the File

  • Replace Placeholder Values: Ensure you replace placeholder values such as YourAppName, com.yourcompany.yourapp, and the version numbers with your actual app details.
  • Carrier Information: Fill in the actual MNC, MCC, GID1, and GID2 values provided by your carrier partner.

Approval process

Becoming approved:

To be approved by Apple for eSIM entitlement, a developer needs to prepare and fulfill several requirements. Here’s an overview of the steps and necessary preparations:

1. Apple Developer Program Membership

  • Ensure you are enrolled in the Apple Developer Program. This membership provides access to the tools and resources needed to develop and distribute apps on Apple platforms.

2. Carrier Agreement

  • You must have a formal agreement with a supported carrier. Apple works with specific carriers that support eSIM functionality. You need to partner with one of these carriers and fulfill their requirements for eSIM provisioning.

3. Implementing eSIM Support in Your App

  • CTCellularPlanProvisioningRequest API: Implement the CTCellularPlanProvisioningRequest API to request the addition of a cellular plan.
  • App Configuration: Your app needs to be configured correctly to utilize this API. This includes handling user authentication and authorization for adding plans.

4. Entitlement Application

  • Apply for the Entitlement: Use the Apple Developer portal to apply for the eSIM entitlement. This will involve providing detailed information about your app and its intended use of the eSIM functionality.
  • Review Process: Apple will review your application. This review includes verifying your agreement with a supported carrier and evaluating your app’s use case to ensure it complies with Apple’s guidelines.

5. Security and Privacy Compliance

  • User Data Protection: Ensure your app complies with Apple’s security and privacy guidelines, particularly regarding user data protection and privacy.
  • Token/Key Management: Properly manage any tokens or keys required for eSIM activation, ensuring they are securely handled within your app.

6. Testing and Validation

  • Testing with Carrier: Collaborate with your carrier partner to test the eSIM provisioning process. This ensures that your app correctly interfaces with the carrier’s systems and Apple’s APIs.
  • Beta Testing: Conduct thorough testing with beta users to identify and fix any issues before wider deployment.

7. Documentation and Support

  • User Documentation: Provide clear documentation and support for users on how to use the eSIM functionality within your app.
  • Developer Support: Be prepared to address any technical issues or questions that may arise during the review and deployment process.

Resources

  1. Apple Developer Documentation
  2. Apple Developer Forums
  3. Technical Blogs and Articles
  4. Apple Support

How can eSIM Access help?

eSIM Access and parent Redtea Mobile can help with your application. We have successfully integrated in app provisioning in consumer apps like RedteaGO and others. 

If you maintain an established iOS Application with thousands of ratings and tens of thousands of downloads, we may be able to help add eSIM provisioning to your application.    

View details for Android.