@capgo/capacitor-network-diagnostics

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

Capacitor plugin for native network diagnostics. It checks connection type, native HTTP reachability, TCP ports, WebSocket handshakes, download speed, and application-level packet loss from iOS and Android.

Install

npm install @capgo/capacitor-network-diagnostics
npx cap sync

What It Tests

• Current native connection type: WiFi, cellular, ethernet, VPN, none, or unknown.
• OS network flags: validated internet on Android, captive portal on Android, expensive or constrained path where available.
• Native HTTP/HTTPS URL reachability with status code and latency.
• Native TCP host:port connectivity.
• Native WebSocket handshake for ws:// and wss://.
• Download throughput against your own test file endpoint.
• Packet loss using repeated TCP connects or HTTP requests.

Raw ICMP ping is not consistently available to App Store and Play Store apps. testPacketLoss therefore measures application-level loss with TCP or HTTP probes.

Usage

import { NetworkDiagnostics } from '@capgo/capacitor-network-diagnostics';

const status = await NetworkDiagnostics.getNetworkStatus();

const api = await NetworkDiagnostics.testUrl({
  url: 'https://api.example.com/health',
  method: 'HEAD',
  timeoutMs: 5000,
});

const port = await NetworkDiagnostics.testPort({
  host: 'api.example.com',
  port: 443,
  timeoutMs: 3000,
});

const ws = await NetworkDiagnostics.testWebSocket({
  url: 'wss://ws.example.com/socket',
  timeoutMs: 5000,
});

const packetLoss = await NetworkDiagnostics.testPacketLoss({
  mode: 'tcp',
  host: 'api.example.com',
  port: 443,
  count: 10,
});

console.log({ status, api, port, ws, packetLoss });

Combined Diagnostic Run

const report = await NetworkDiagnostics.runDiagnostics({
  urls: [{ url: 'https://api.example.com/health' }],
  ports: [{ host: 'api.example.com', port: 443 }],
  websockets: [{ url: 'wss://ws.example.com/socket' }],
  download: {
    url: 'https://speed.example.com/5mb.bin',
    maxBytes: 5 * 1024 * 1024,
  },
  packetLoss: {
    mode: 'tcp',
    host: 'api.example.com',
    port: 443,
    count: 10,
  },
});

console.log(report.issues);

Platform Notes

• iOS: no extra permissions are required. Connection type comes from Network.framework.
• Android: the plugin declares android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE.
• Web: provided as a development fallback. Browsers cannot open raw TCP sockets, and URL checks are limited by CORS.

API

• getNetworkStatus()
• testUrl(...)
• testPort(...)
• testWebSocket(...)
• testDownloadSpeed(...)
• testPacketLoss(...)
• runDiagnostics(...)
• getPluginVersion()
• Interfaces
• Type Aliases

Native network diagnostics API.

getNetworkStatus()

getNetworkStatus() => Promise<NetworkStatusResult>

Read the current native connection type and platform network flags.

Returns: Promise<NetworkStatusResult>

---

testUrl(...)

testUrl(options: UrlTestOptions) => Promise<UrlTestResult>

Test whether an HTTP or HTTPS URL can be reached from native networking.

Param	Type
options	UrlTestOptions

Returns: Promise<UrlTestResult>

---

testPort(...)

testPort(options: PortTestOptions) => Promise<PortTestResult>

Test whether a TCP host:port can be opened from native networking.

Param	Type
options	PortTestOptions

Returns: Promise<PortTestResult>

---

testWebSocket(...)

testWebSocket(options: WebSocketTestOptions) => Promise<WebSocketTestResult>

Test whether a WebSocket URL can complete its native handshake.

Param	Type
options	WebSocketTestOptions

Returns: Promise<WebSocketTestResult>

---

testDownloadSpeed(...)

testDownloadSpeed(options: DownloadSpeedTestOptions) => Promise<DownloadSpeedTestResult>

Measure download throughput from a native HTTP request.

Param	Type
options	DownloadSpeedTestOptions

Returns: Promise<DownloadSpeedTestResult>

---

testPacketLoss(...)

testPacketLoss(options: PacketLossTestOptions) => Promise<PacketLossTestResult>

Estimate application-level packet loss with repeated TCP or HTTP probes.

Param	Type
options	PacketLossTestOptions

Returns: Promise<PacketLossTestResult>

---

runDiagnostics(...)

runDiagnostics(options?: RunDiagnosticsOptions | undefined) => Promise<RunDiagnosticsResult>

Run several diagnostics and return a compact issue list.

Param	Type
options	RunDiagnosticsOptions

Returns: Promise<RunDiagnosticsResult>

---

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

---

Interfaces

NetworkStatusResult

Current native network state.

Prop	Type	Description
connected	boolean	True when the platform reports an active network path.
connectionType	ConnectionType	Best-effort active transport type.
internetReachable	boolean	True when the OS marks the network as internet-capable or validated.
expensive	boolean	True for metered or expensive network paths.
constrained	boolean	True when the OS reports a low-data or constrained network path.
captivePortal	boolean	True when Android reports captive portal capability.
details	Record<string, string | number | boolean>	Native platform details useful for debugging.

UrlTestResult

Native HTTP URL reachability result.

Prop	Type
url	string
method	UrlTestMethod
ok	boolean
reachable	boolean
durationMs	number
statusCode	number
finalUrl	string
errorCode	string
errorMessage	string

UrlTestOptions

Options for native HTTP URL reachability checks.

Prop	Type	Description
url	string	HTTP or HTTPS URL to test.
method	UrlTestMethod	HTTP method. Defaults to HEAD.
timeoutMs	number	Request timeout in milliseconds. Defaults to 10000.
followRedirects	boolean	Follow redirects. Defaults to true.

PortTestResult

Native TCP port check result.

Prop	Type
host	string
port	number
open	boolean
durationMs	number
errorCode	string
errorMessage	string

PortTestOptions

Options for native TCP port checks.

Prop	Type	Description
host	string	Hostname or IP address.
port	number	TCP port to open.
timeoutMs	number	Socket timeout in milliseconds. Defaults to 5000.

WebSocketTestResult

Native WebSocket handshake result.

Prop	Type
url	string
open	boolean
durationMs	number
protocol	string
statusCode	number
errorCode	string
errorMessage	string

WebSocketTestOptions

Options for native WebSocket handshake checks.

Prop	Type	Description
url	string	ws:// or wss:// URL to test.
timeoutMs	number	Handshake timeout in milliseconds. Defaults to 10000.

DownloadSpeedTestResult

Native download speed measurement result.

Prop	Type
url	string
ok	boolean
durationMs	number
bytesDownloaded	number
bytesPerSecond	number
mbps	number
statusCode	number
errorCode	string
errorMessage	string

DownloadSpeedTestOptions

Options for native download speed measurement.

Prop	Type	Description
url	string	HTTP or HTTPS URL returning a downloadable body.
maxBytes	number	Maximum bytes to read before stopping. Defaults to 5242880 (5 MiB).
timeoutMs	number	Request timeout in milliseconds. Defaults to 30000.

PacketLossTestResult

Application-level packet loss result.

Prop	Type
mode	PacketLossMode
target	string
sent	number
received	number
lost	number
lossPercent	number
averageLatencyMs	number
minLatencyMs	number
maxLatencyMs	number
errorCode	string
errorMessage	string

PacketLossTestOptions

Options for packet loss measurement.

Native apps cannot rely on raw ICMP ping on both iOS and Android, so this method measures application-level loss with repeated TCP connects or HTTP requests.

Prop	Type	Description
mode	PacketLossMode	Probe mode. Defaults to tcp when host/port is provided, otherwise http.
host	string	Hostname or IP address for TCP probes.
port	number	TCP port for TCP probes.
url	string	HTTP or HTTPS URL for HTTP probes.
count	number	Number of probes to send. Defaults to 10.
timeoutMs	number	Per-probe timeout in milliseconds. Defaults to 3000.
intervalMs	number	Delay between probes in milliseconds. Defaults to 250.

RunDiagnosticsResult

Combined native network diagnostic result.

Prop	Type
status	NetworkStatusResult
urls	UrlTestResult[]
ports	PortTestResult[]
websockets	WebSocketTestResult[]
issues	string[]
download	DownloadSpeedTestResult
packetLoss	PacketLossTestResult

RunDiagnosticsOptions

Options for a combined native network diagnostic run.

Prop	Type
urls	UrlTestOptions[]
ports	PortTestOptions[]
websockets	WebSocketTestOptions[]
download	DownloadSpeedTestOptions
packetLoss	PacketLossTestOptions

PluginVersionResult

Plugin version payload.

Prop	Type	Description
version	string	Version identifier returned by the platform implementation.

Type Aliases

ConnectionType

'none' | 'wifi' | 'cellular' | 'ethernet' | 'vpn' | 'other' | 'unknown'

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

UrlTestMethod

'HEAD' | 'GET'

PacketLossMode

'tcp' | 'http'