@capgo/capacitor-network-diagnostics

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'