Skip to content

Latest commit

 

History

History
204 lines (143 loc) · 4.91 KB

README.md

File metadata and controls

204 lines (143 loc) · 4.91 KB

📱 react-native-sim-cards-manager

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

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