https://github.com/odemolliens/react-native-sim-cards-manager
React Native plugin to manage Sim card(s) & eSim
https://github.com/odemolliens/react-native-sim-cards-manager
Last synced: 3 months ago
JSON representation
React Native plugin to manage Sim card(s) & eSim
- Host: GitHub
- URL: https://github.com/odemolliens/react-native-sim-cards-manager
- Owner: odemolliens
- License: mit
- Created: 2022-03-08T11:13:33.000Z (over 3 years ago)
- Default Branch: develop
- Last Pushed: 2024-05-29T06:45:46.000Z (about 1 year ago)
- Last Synced: 2024-05-29T19:32:59.261Z (about 1 year ago)
- Language: Java
- Homepage:
- Size: 962 KB
- Stars: 52
- Watchers: 6
- Forks: 24
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 📱 react-native-sim-cards-manager
A unified library merging features from multiple SIM card management libraries:
- [react-native-esim](https://github.com/markneh/react-native-esim)
- [react-native-sim-data](https://github.com/pocesar/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:
```sh
npm install react-native-sim-cards-manager
```
---
## 🛠 Debugging
### Android
To debug device logs during eSIM setup, use the following command:
```sh
adb logcat | grep "Euicc"
```
---
## 🔐 Permissions
### Android
- **Minimum API Level:** 22
- Add the following permission in `AndroidManifest.xml` for `TelephonyManager`:
```xml
```
For **eSIM features**:
- For regular apps, follow the instructions in the [carrier privileges guide](https://source.android.com/docs/core/connect/esim-overview#carrier-privileges).
- For system apps, include the following permission:
```xml
```
More details [here](https://source.android.com/devices/tech/connect/esim-euicc-api#download-sub).
### iOS
- **Minimum API Level:** 12 (eSIM features)
- Requires eSIM entitlement. Learn more [here](https://stackoverflow.com/a/60162323).
⚠️ **Note:** As of iOS 14.2, there is a known bug where an unknown result may be returned before completing eSIM setup. Details [here](https://developer.apple.com/forums/thread/662001).
---
## 📖 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.
```ts
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) => {
// Handle results
})
.catch((error) => {
// Handle errors
});
```
#### 📌 Method: `getSimCardsNative`
Used internally by `getSimCards`. Does not handle permissions.
```ts
import SimCardsManagerModule from 'react-native-sim-cards-manager';
SimCardsManagerModule.getSimCardsNative()
.then((array: Array) => {
// 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.
```ts
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. |
```ts
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](CONTRIBUTING.md) for details on how to contribute to the project.
---
## 📜 License
MIT License.
---