@kevindupas/capacitor-network-quality

Android TelephonyManager plugin for Capacitor — signal metrics (RSRP, RSRQ, SINR, RSSI, CQI), cell identity (CI, PCI, TAC, EARFCN), network type (2G/3G/LTE/5G), VoLTE, 5G NSA detection, IP version, MCC/MNC.

iOS note: Raw radio indicators (RSRP, RSRQ, SINR, RSSI), network generation, and SIM operator are not accessible on iOS due to Apple platform restrictions. This plugin is Android-only for radio data.

Install

npm install @kevindupas/capacitor-network-quality
npx cap sync

Android setup

Add to AndroidManifest.xml (before or after the application tag):

<uses-permission android:name="android.permission.READ_BASIC_PHONE_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

READ_PHONE_STATE is required for TelephonyDisplayInfo (5G NSA detection) and getDataNetworkType(). READ_BASIC_PHONE_STATE alone is not sufficient for these APIs. ACCESS_FINE_LOCATION is required for getAllCellInfo() (raw signal metrics). All are runtime permissions — the plugin requests them automatically.

Changelog

1.0.3

• Added: ci (Cell Identity), pci (Physical Cell ID), tac (Tracking Area Code), earfcn (radio frequency channel) to getRadioInfo() — available for LTE, NR (5G), and WCDMA cells.
• These fields are essential for antenna-level network cartography (regulatory use).

1.0.2

• Fixed: READ_PHONE_STATE added to plugin @Permission declaration — required for TelephonyDisplayInfo (5G NSA) and getDataNetworkType(). READ_BASIC_PHONE_STATE alone was silently blocking these APIs.
• Fixed: checkPermission() now always checks READ_PHONE_STATE (not READ_BASIC_PHONE_STATE on Android 13+) — only READ_PHONE_STATE grants access to cell info and network type APIs.
• Fixed: getRadioInfo() now requests both phone_state and location permissions, not just location.

1.0.1

• Fixed: checkPermission() now requires ACCESS_FINE_LOCATION (was missing — caused all radio metrics to return null on Android 9+).
• Fixed: isNrAvailable uses getDataNetworkType(true) for correct 5G detection on Android 13+.

Usage

import { NetworkQuality } from '@kevindupas/capacitor-network-quality';

// Basic info — no permission required
const info = await NetworkQuality.getInfo();
// { signalStrengthLevel: 'GOOD', simOperatorName: 'Safaricom', dataState: 'CONNECTED', mcc: '639', mnc: '02' }

// Raw signal metrics — requires READ_PHONE_STATE + ACCESS_FINE_LOCATION
const radio = await NetworkQuality.getRadioInfo();
// {
//   rsrp: -85, rsrq: -10, sinr: 15, rssi: -75, cqi: 12,
//   ci: 12345678, pci: 42, tac: 5020, earfcn: 1300,
//   isVoLteAvailable: true, isNrAvailable: false, ipVersion: 'dual'
// }

// Network type — requires READ_PHONE_STATE
const { type } = await NetworkQuality.getNetworkType();
// 'LTE' | '5G' | '3G' | '2G' | 'UNKNOWN'

API

• checkPermissions()
• requestPermissions()
• getInfo()
• getRadioInfo()
• getNetworkType(...)
• Interfaces
• Type Aliases
• Enums

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check current permission status for phone state and location.

Returns: Promise<PermissionStatus>

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request phone state and location permissions from the user.

Returns: Promise<PermissionStatus>

getInfo()

getInfo() => Promise<NetworkInfo>

Returns basic network info: signal level, operator name, data state, MCC/MNC. Available on Android only.

Returns: Promise<NetworkInfo>

getRadioInfo()

getRadioInfo() => Promise<RadioInfo>

Returns extended radio information: raw signal metrics (RSRP, RSRQ, SINR, RSSI, CQI), VoLTE/VoNR availability, and IP version. Requires READ_PHONE_STATE + ACCESS_FINE_LOCATION permissions on Android. Not available on iOS (Apple platform restriction).

Returns: Promise<RadioInfo>

getNetworkType(...)

getNetworkType(options?: { withBasicPermission?: boolean | undefined; } | undefined) => Promise<{ type: NetworkType; }>

Returns the current data network type (2G, 3G, LTE, 5G). Available on Android only.

| Param | Type | | ------------- | ----------------------------------------------- | | options | { withBasicPermission?: boolean; } |

Returns: Promise<{ type: NetworkType; }>

Interfaces

PermissionStatus

| Prop | Type | | ----------------- | ----------------------------------------------------------- | | phone_state | PermissionState | | location | PermissionState |

NetworkInfo

| Prop | Type | Description | | ------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | dataState | DataState | | | signalStrengthLevel | SignalStrengthLevel | | | simOperatorName | string | | | mcc | string | null | Mobile Country Code (3 digits, e.g. "639" for Kenya). null if SIM absent or operator string unavailable. | | mnc | string | null | Mobile Network Code (2–3 digits, e.g. "02" for Safaricom Kenya). null if SIM absent or operator string unavailable. |

RadioInfo

| Prop | Type | Description | | ------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | signalStrengthLevel | SignalStrengthLevel | | | rsrp | number | null | Reference Signal Received Power in dBm (LTE/NR). Typical range: -44 (excellent) to -140 (no signal). null if unavailable. | | rsrq | number | null | Reference Signal Received Quality in dB (LTE/NR). Typical range: -3 (excellent) to -20 (poor). null if unavailable. | | sinr | number | null | Signal-to-Interference-plus-Noise Ratio in dB (LTE/NR). Typical range: +30 (excellent) to -20 (poor). null if unavailable. | | rssi | number | null | Received Signal Strength Indicator in dBm (WCDMA/3G or LTE). Typical range: -50 (excellent) to -100 (poor). null if unavailable. | | cqi | number | null | Channel Quality Indicator (LTE only, 0–15). null if unavailable. | | ci | number | null | Cell Identity — unique identifier of the serving cell (LTE: CI, NR: NCI, WCDMA: CID). Key field for antenna-level network mapping. null if unavailable. | | pci | number | null | Physical Cell ID — identifies the cell on the radio layer (LTE/NR: 0–503, WCDMA: null). Used to distinguish cells on the same frequency. null if unavailable. | | tac | number | null | Tracking Area Code — groups cells for paging (LTE/NR only). null if unavailable. | | earfcn | number | null | Radio frequency channel number (LTE: EARFCN, NR: NR-ARFCN, WCDMA: UARFCN). Identifies the radio frequency band in use. null if unavailable. | | isVoLteAvailable | boolean | null | Whether VoLTE is supported by device and network. Android 12+ only. | | isNrAvailable | boolean | null | Whether VoNR / 5G NR is available. Android 12+ only. | | ipVersion | IpVersion | Detected IP version: "IPv4", "IPv6", "dual", or "unknown". |

Type Aliases

PermissionState

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

Enums

DataState

| Members | Value | | -------------------------- | ----------------------------------- | | UNKNOWN | "UNKNOWN" | | DISCONNECTED | "DISCONNECTED" | | CONNECTING | "CONNECTING" | | CONNECTED | "CONNECTED" | | SUSPENDED | "SUSPENDED" | | DISCONNECTING | "DISCONNECTING" | | HANDOVER_IN_PROGRESS | "HANDOVER_IN_PROGRESS" |

SignalStrengthLevel

| Members | Value | | -------------- | ----------------------- | | UNKNOWN | "UNKNOWN" | | NONE | "NONE" | | POOR | "POOR" | | MODERATE | "MODERATE" | | GOOD | "GOOD" | | GREAT | "GREAT" |

IpVersion

| Members | Value | | ------------- | ---------------------- | | UNKNOWN | "unknown" | | IPV4 | "IPv4" | | IPV6 | "IPv6" | | DUAL | "dual" |

NetworkType

| Members | Value | | ------------- | ---------------------- | | UNKNOWN | "UNKNOWN" | | TWO_G | "2G" | | THREE_G | "3G" | | LTE | "LTE" | | FIVE_G | "5G" |