📱 react-native-sim-cards-manager

A unified library merging features from multiple SIM card management libraries:

• react-native-esim
• react-native-sim-data

🚀 Why use this library?

✅ Unified APIs for eSIM and SIM data management.
✅ Bug fixes and enhancements for improved stability.
✅ Simplified transition from previous libraries (requires some code adaptation).

📦 Installation

Install the package using npm:

npm install react-native-sim-cards-manager

🛠 Debugging

Android

To debug device logs during eSIM setup, use the following command:

adb logcat | grep "Euicc"

🔐 Permissions

Android

• Minimum API Level: 22
• Add the following permission in AndroidManifest.xml for TelephonyManager:

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

For eSIM features:

• For regular apps, follow the instructions in the carrier privileges guide.
• For system apps, include the following permission:

<uses-permission android:name="android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS" />

More details here.

iOS

• Minimum API Level: 12 (eSIM features)
• Requires eSIM entitlement. Learn more here.

⚠️ Note: As of iOS 14.2, there is a known bug where an unknown result may be returned before completing eSIM setup. Details here.

📖 Usage

📲 Retrieve SIM Cards

Fetch a list of SIM cards. The result may contain no elements (if no SIM cards are detected) or multiple entries.

📌 Method: getSimCards

Handles permission requests and accepts an optional _rationale_ parameter.

import SimCardsManagerModule from 'react-native-sim-cards-manager';

SimCardsManagerModule.getSimCards({
  title: 'App Permission',
  message: 'Custom message',
  buttonNeutral: 'Not now',
  buttonNegative: 'Not OK',
  buttonPositive: 'OK',
})
  .then((array: Array<any>) => {
    // Handle results
  })
  .catch((error) => {
    // Handle errors
  });

📌 Method: getSimCardsNative

Used internally by getSimCards. Does not handle permissions.

import SimCardsManagerModule from 'react-native-sim-cards-manager';

SimCardsManagerModule.getSimCardsNative()
  .then((array: Array<any>) => {
    // Handle results
  })
  .catch((error) => {
    // Handle errors
  });

📊 Available Data

| Field | iOS | Android | | ------------------|-----|---------| | carrierName | ✅ | ✅ | | displayName | ❌ | ✅ | | isoCountryCode | ✅ | ✅ | | mobileCountryCode | ✅ | ✅ | | mobileNetworkCode | ✅ | ✅ | | isNetworkRoaming | ❌ | ✅ | | isDataRoaming | ❌ | ✅ | | simSlotIndex | ❌ | ✅ | | phoneNumber | ❌ | ✅ | | simSerialNumber | ❌ | ✅ | | subscriptionId | ❌ | ✅ | | allowsVOIP | ✅ | ❌ |

🔍 eSIM Support Check

Verify if the device supports eSIM functionality.

import SimCardsManagerModule from 'react-native-sim-cards-manager';

SimCardsManagerModule.isEsimSupported()
  .then((isSupported: boolean) => {
    // Handle result
  })
  .catch((error) => {
    // Handle errors
  });

⚙️ eSIM Setup

Configure an eSIM using an activation code.

📌 Parameters

| Field | Mandatory | Description | |------------------|-----------|-------------| | address | N/A | Carrier network's eSIM server address. | | confirmationCode | N/A | Confirmation code for eSIM provisioning. | | eid | N/A | eUICC identifier. | | iccid | N/A | Integrated Circuit Card Identifier. | | matchingId | N/A | Matching identifier for the eSIM profile. | | oid | N/A | Object Identifier for the provisioning request. |

⚠️ Error Codes

| Code | Description | |------------------|-------------| | 0 | Feature not available. | | 1 | Device does not support cellular plans. | | 2 | OS failed to add the plan. | | 3 (iOS) | Unknown OS error. | | 3 (Android) | OS or Intent/Activity error. |

import SimCardsManagerModule from 'react-native-sim-cards-manager';

SimCardsManagerModule.setupEsim({
  confirmationCode,
  address: '',
})
  .then((isPlanAdded: boolean) => {
    // Handle success
  })
  .catch((error) => {
    // Handle errors
  });

👨‍💻 Contributing

Read the Contributing Guide for details on how to contribute to the project.

📜 License

MIT License.