@capgo/capacitor-sim

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/sim/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

npm install @capgo/capacitor-sim
npx cap sync

Usage

import { Sim } from '@capgo/capacitor-sim';

const loadSimCards = async () => {
  const { simCards } = await Sim.getSimCards();

  return simCards;
};

The returned simCards array contains carrier information for each detected SIM. On Android the list also exposes the subscriptionId and simSlotIndex values so you can correlate entries across platform APIs.

iOS 16.4+ limitations

Starting with iOS 16.4 Apple restricts access to several carrier fields returned by CoreTelephony. On devices running iOS 16.4 or newer the plugin may return placeholder values such as 65535, --, or empty strings for carrierName, isoCountryCode, mobileCountryCode, and mobileNetworkCode. This behaviour is handled at the OS level and is tracked upstream in jonz94/capacitor-sim#8; there is currently no known workaround besides relying on Android data or older iOS versions.

API

• getSimCards()
• checkPermissions()
• requestPermissions()
• getPluginVersion()
• Interfaces
• Type Aliases

Capacitor SIM Plugin for retrieving information from device SIM cards.

This plugin provides access to SIM card information such as carrier name, country code, mobile network codes, and more. Supports dual-SIM devices.

getSimCards()

getSimCards() => Promise<GetSimCardsResult>

Get information from the device's SIM cards.

Retrieves details about all SIM cards installed in the device. On dual-SIM devices, returns information for both SIM cards. Requires READ_PHONE_STATE permission on Android.

Returns: Promise<GetSimCardsResult>

Since: 1.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permission to access SIM card information.

Checks if the app has permission to read SIM card data. On Android, checks READ_PHONE_STATE permission. On iOS, the status is always granted. On Web, the status is always denied.

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to access SIM card information.

Prompts the user to grant permission to read SIM card data. On Android, requests READ_PHONE_STATE permission. On iOS, the status is always granted without prompting. On Web, the status remains denied.

Returns: Promise<PermissionStatus>

Since: 1.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

GetSimCardsResult

Result returned by {@link SimPlugin.getSimCards}.

| Prop | Type | | -------------- | ---------------------- | | simCards | SimCard[] |

SimCard

A SIM card description.

| Prop | Type | Description | Since | | ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | number | string | Android only: Phone number for this SIM slot, when available. | 1.0.0 | | subscriptionId | string | Android only: Unique subscription identifier. | 1.1.0 | | simSlotIndex | number | Android only: Physical SIM slot index for this subscription. | 1.1.0 | | allowsVOIP | boolean | iOS only: Indicates whether the carrier supports VoIP. | 1.0.0 | | carrierName | string | Display name of the cellular service provider. On iOS 16.4+ the system may return placeholder values such as --. See https://github.com/jonz94/capacitor-sim/issues/8 for details. | 1.0.0 | | isoCountryCode | string | ISO 3166-1 alpha-2 country code of the service provider. On iOS 16.4+ the system may return an empty string or --. See https://github.com/jonz94/capacitor-sim/issues/8 for details. | 1.0.0 | | mobileCountryCode | string | Mobile Country Code (MCC) of the service provider. On iOS 16.4+ the system may return placeholder values such as 65535. See https://github.com/jonz94/capacitor-sim/issues/8 for details. | 1.0.0 | | mobileNetworkCode | string | Mobile Network Code (MNC) of the service provider. On iOS 16.4+ the system may return placeholder values such as 65535. See https://github.com/jonz94/capacitor-sim/issues/8 for details. | 1.0.0 |

PermissionStatus

Result of a permission check or request.

| Prop | Type | | ----------------- | ----------------------------------------------------------- | | readSimCard | PermissionState |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'