@capawesome/capacitor-sim 0.0.1 → 0.1.1

package/README.md

@@ -1,4 +1,4 @@
-# @capawesome/capacitor-sim
+# Capacitor SIM Plugin
 
 Capacitor plugin for reading SIM card and carrier information.
 
@@ -18,9 +18,14 @@ Capacitor plugin for reading SIM card and carrier information.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The SIM plugin is typically used when an app needs to know about the device's SIM cards or carrier, for example:
+
+- **Carrier-specific features**: Enable or disable functionality depending on the carrier name or the MCC and MNC of the SIM card.
+- **Country detection**: Use the SIM card's ISO country code to preselect a country or region in your app.
+- **Multi-SIM handling**: Show which SIM slots are in use on devices with multiple SIM slots.
+- **eSIM detection**: Detect whether a SIM card is an embedded SIM (eSIM).
 
 ## Compatibility
 
@@ -66,6 +71,12 @@ No configuration required for this plugin.
 
 ## Usage
 
+The following examples show how to check and request permissions and read the SIM cards installed on the device.
+
+### Check and request permissions
+
+Reading the SIM cards requires the `READ_PHONE_STATE` runtime permission on Android. Check the current permission state and request the permission before calling `getSimCards(...)`. Only available on Android:
+
 ```typescript
 import { Sim } from '@capawesome/capacitor-sim';
 
@@ -78,6 +89,14 @@ const requestPermissions = async () => {
   const { readSimCards } = await Sim.requestPermissions();
   return readSimCards;
 };
+```
+
+### Read the SIM cards
+
+Get information about the SIM cards installed on the device, such as the carrier name, country code, MCC and MNC. On devices with multiple SIM slots, all active SIM cards are returned. Only available on Android:
+
+```typescript
+import { Sim } from '@capawesome/capacitor-sim';
 
 const getSimCards = async () => {
   const { simCards } = await Sim.getSimCards();
@@ -193,6 +212,46 @@ Only available on Android.
 
 </docgen-api>
 
+## FAQ
+
+### How is this plugin different from other similar plugins?
+
+It reads the full picture of the device's SIM cards in a single call — carrier name, ISO country code, MCC and MNC, eSIM status, and the slot index for every active card on multi-SIM devices — through a fully typed API that handles the required Android runtime permission for you. It's honest about platform reality, too: SIM data is well supported on Android, while iOS no longer exposes it reliably, so the plugin focuses where the information is actually available. If you only need a rough country hint, a lighter approach may be enough; if you need dependable multi-SIM and carrier details, this plugin is built for exactly that.
+
+### Why is the SIM plugin not available on iOS?
+
+Apple deprecated the `CTCarrier` APIs of the Core Telephony framework with iOS 16, and they return placeholder values (e.g. `"--"` and `65535`) on iOS 16.4 and later. Because there is no reliable system API left for reading SIM card and carrier information, all methods reject as unimplemented on iOS. See the [iOS installation notes](#ios) for details.
+
+### Which permissions are required to read the SIM cards?
+
+The plugin requires the `READ_PHONE_STATE` permission on Android. It is declared in the plugin's `AndroidManifest.xml` and merged into your app automatically, so no manual manifest changes are needed. However, you must request the permission at runtime via the `requestPermissions` method before calling `getSimCards`.
+
+### Why is the phone number `null`?
+
+The `phoneNumber` property is often empty because carriers do not reliably store the phone number on the SIM card. In that case, the plugin returns `null`. Other properties such as `carrierName` or `isoCountryCode` may also be `null` if the information is not available.
+
+### Does the plugin support dual-SIM devices?
+
+Yes, on devices with multiple SIM slots, the `getSimCards` method returns all active SIM cards. Each SIM card includes a `slotIndex` property that indicates the index of the SIM slot on the device.
+
+### Can I detect whether a SIM card is an eSIM?
+
+Yes, each SIM card includes an `isEmbedded` property that indicates whether it is an embedded SIM (eSIM). The property returns `null` if the information is not available.
+
+### Can I use this plugin with Ionic, React, Vue or Angular?
+
+Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
+
+## Related Plugins
+
+- [Device Info](https://capawesome.io/docs/sdks/capacitor/device-info/): Read device information, such as the model, manufacturer, and operating system.
+- [Network](https://capawesome.io/docs/sdks/capacitor/network/): Access network information.
+- [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/sim/CHANGELOG.md).

package/android/build.gradle

@@ -30,7 +30,7 @@ android {
     buildTypes {
         release {
             minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
     lintOptions {

package/ios/Plugin/SimPlugin.swift

@@ -6,7 +6,9 @@ public class SimPlugin: CAPPlugin, CAPBridgedPlugin {
     public let identifier = "SimPlugin"
     public let jsName = "Sim"
     public let pluginMethods: [CAPPluginMethod] = [
-        CAPPluginMethod(name: "getSimCards", returnType: CAPPluginReturnPromise)
+        CAPPluginMethod(name: "checkPermissions", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getSimCards", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "requestPermissions", returnType: CAPPluginReturnPromise)
     ]
 
     @objc override public func checkPermissions(_ call: CAPPluginCall) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capawesome/capacitor-sim",
-  "version": "0.0.1",
-  "description": "Capacitor plugin for reading SIM card and carrier information.",
+  "version": "0.1.1",
+  "description": "Capacitor plugin for reading SIM card and carrier information on Android.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -33,11 +33,20 @@
       "url": "https://opencollective.com/capawesome"
     }
   ],
-  "homepage": "https://capawesome.io/docs/plugins/sim/",
+  "homepage": "https://capawesome.io/docs/sdks/capacitor/sim/",
   "keywords": [
     "capacitor",
     "plugin",
-    "native"
+    "native",
+    "capacitor-plugin",
+    "sim",
+    "sim card",
+    "esim",
+    "carrier",
+    "carrier information",
+    "dual sim",
+    "mcc",
+    "mnc"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",