📱 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.

---