@capgo/capacitor-network-diagnostics

Find out why your Capacitor app cannot reach your backend: test connection type, HTTP reachability, TCP ports, WebSockets, download speed and packet loss from the device itself.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-network-diagnostics in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-network-diagnostics to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Network status: getNetworkStatus() returns the native connection type and network flags.
• Reachability: testUrl() for HTTP or HTTPS and testPort() for a TCP host and port.
• WebSockets: testWebSocket() checks that a handshake completes.
• Performance: testDownloadSpeed() and testPacketLoss().
• One report: runDiagnostics() runs several checks and returns a compact summary.
• Platforms: iOS, Android and Web. Web runs the browser-capable checks. TCP port tests need native code.

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()
• 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.

Returns: Promise<UrlTestResult>

testPort(...)

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

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

Returns: Promise<PortTestResult>

testWebSocket(...)

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

Test whether a WebSocket URL can complete its native handshake.

Returns: Promise<WebSocketTestResult>

testDownloadSpeed(...)

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

Measure download throughput from a native HTTP request.

Returns: Promise<DownloadSpeedTestResult>

testPacketLoss(...)

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

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

Returns: Promise<PacketLossTestResult>

runDiagnostics(...)

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

Run several diagnostics and return a compact issue list.

Returns: Promise<RunDiagnosticsResult>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

NetworkStatusResult

Current native network state.

UrlTestResult

Native HTTP URL reachability result.

UrlTestOptions

Options for native HTTP URL reachability checks.

PortTestResult

Native TCP port check result.

PortTestOptions

Options for native TCP port checks.

WebSocketTestResult

Native WebSocket handshake result.

WebSocketTestOptions

Options for native WebSocket handshake checks.

DownloadSpeedTestResult

Native download speed measurement result.

DownloadSpeedTestOptions

Options for native download speed measurement.

PacketLossTestResult

Application-level packet loss result.

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.

RunDiagnosticsResult

Combined native network diagnostic result.

RunDiagnosticsOptions

Options for a combined native network diagnostic run.

PluginVersionResult

Plugin version payload.

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'