react-native-sim-cards-manager React Native pl @codeKK AndroidOpen Source Website

react-native-sim-cards-manager

Project Url: odemolliens/react-native-sim-cards-manager

Introduction: React Native plugin to manage Sim card(s) & eSim

Tags:

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
  });