@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

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-network-diagnostics` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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() => Promise<NetworkStatusResult>

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

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

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

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

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

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

getPluginVersion() => Promise<PluginVersionResult>