Getting Started

Install

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

Import

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

Run a complete diagnostic report

runDiagnostics is the fastest way to collect a support report for a user on a restricted network.

const report = await NetworkDiagnostics.runDiagnostics({
  urls: [{ url: 'https://api.example.com/health', method: 'HEAD' }],
  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.status.connectionType);
console.log(report.issues);

Check current network status

const status = await NetworkDiagnostics.getNetworkStatus();

console.log(status.connected);
console.log(status.connectionType);
console.log(status.internetReachable);
console.log(status.captivePortal);

The exact flags depend on the platform. Android can report validated internet and captive portal state. iOS reports path status, interface type, expensive paths, and constrained paths through Network.framework.

Test API reachability

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

if (!result.reachable) {
  console.warn(result.errorCode, result.errorMessage);
}

Use a real health endpoint from your backend. A browser-only check can be hidden by WebView, CORS, proxy, or captive portal behavior, while this plugin uses native networking.

Test a TCP port

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

console.log(port.open, port.durationMs);

This is useful when a Wi-Fi access point blocks non-standard ports, MQTT, custom gateways, or a private backend while still allowing normal browsing.

Test WebSocket connectivity

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

console.log(socket.open, socket.statusCode);

Use this when proxies or captive portals allow HTTPS pages but block WebSocket upgrade requests.

Measure download speed

const speed = await NetworkDiagnostics.testDownloadSpeed({
  url: 'https://speed.example.com/5mb.bin',
  maxBytes: 5 * 1024 * 1024,
  timeoutMs: 30000,
});

console.log(speed.mbps);

Use your own static file endpoint so the result reflects the network path your app needs.

Estimate packet loss

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

console.log(loss.lossPercent);

Raw ICMP ping is not portable in App Store and Play Store apps. This method measures application-level packet loss by repeating TCP or HTTP probes.

Web fallback

The web implementation is meant for development. Browsers cannot open raw TCP sockets, and URL checks may be limited by CORS. Use iOS or Android builds for real support diagnostics.