Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-network-diagnostics
bunx cap sync

Importieren

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

Quickstart

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

const result = await NetworkDiagnostics.getNetworkStatus();
console.log(result);

Beispiel: testUrl

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

const result = await NetworkDiagnostics.testUrl({ url: 'https://example.com' });
console.log(result);

Beispiel: testPort

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

const result = await NetworkDiagnostics.testPort({
  host: 'example.com',
  port: 8080,
});
console.log(result);

Häufige Stolperfallen

• Nativer Sync: ausführen bunx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

Vollständigen Diagnosebericht erstellen

runDiagnostics ist der schnellste Weg, um einen Support-Bericht für einen Nutzer in einem eingeschränkten Netzwerk zu erstellen.

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);

Aktuellen Netzwerkstatus prüfen

const status = await NetworkDiagnostics.getNetworkStatus();

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

Die genauen Flags hängen von der Plattform ab. Android kann validiertes Internet und den Captive-Portal-Status melden. iOS meldet Path-Status, Interface-Typ, expensive und constrained Paths über Network.framework.

Erreichbarkeit von API testen

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);
}

Nutze einen echten Health-Endpoint aus deinem Backend. Ein reiner Browser-Check kann durch WebView, CORS, Proxies oder Captive-Portal-Verhalten verfälscht werden, während dieses Plugin natives Networking nutzt.

TCP-Port testen

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

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

Das ist hilfreich, wenn ein Wi-Fi-Access-Point zwar normales Surfen erlaubt, aber Nicht-Standard-Ports, MQTT, Custom Gateways oder ein privates Backend blockiert.

WebSocket-Verbindung testen

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

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

Verwende dies, wenn Proxys oder Captive Portals HTTPS-Seiten zulassen, aber WebSocket-Upgrade-Anfragen blockieren.

Download-Geschwindigkeit messen

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

console.log(speed.mbps);

Nutze deinen eigenen statischen Datei-Endpoint, damit das Ergebnis den Netzwerkpfad widerspiegelt, den deine App braucht.

Paketverlust abschätzen

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

console.log(loss.lossPercent);

Rohes ICMP-Ping ist in App-Store- und Play-Store-Apps nicht portabel. Diese Methode misst Packet Loss auf Anwendungsebene durch wiederholte TCP- oder HTTP-Probes.

Web-Fallback

Die Web-Implementierung ist nur für die Entwicklung gedacht. Browser können keine rohen TCP-Sockets öffnen, und URL-Checks können durch CORS eingeschränkt sein. Nutze iOS- oder Android-Builds für echte Support-Diagnosen.