Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

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

Importa

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

Avvio rapido

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

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

Esempio: testUrl

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

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

Esempio: testPort

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

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

Errori comuni

• Sync nativo: esegui bunx cap sync dopo gli aggiornamenti dei plugin.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Esegui un report diagnostico completo

runDiagnostics è il modo più veloce per raccogliere un report di supporto per un utente su una rete limitata.

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

Controlla lo stato attuale della rete

const status = await NetworkDiagnostics.getNetworkStatus();

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

I flag esatti dipendono dalla piattaforma. Android può riportare lo stato di internet validato e del captive portal. iOS riporta lo stato del path, il tipo di interfaccia, i path costosi e i path con restrizioni tramite Network.framework.

Test della raggiungibilità di API

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

Usa un vero endpoint di health check del tuo backend. Un controllo solo via browser può essere mascherato da WebView, CORS, proxy o dal comportamento del captive portal, mentre questo plugin usa il networking nativo.

Test di una porta TCP

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

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

È utile quando un access point Wi-Fi blocca porte non standard, MQTT, gateway personalizzati o un backend privato, pur permettendo la normale navigazione.

Verifica connettività WebSocket

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

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

Usalo quando proxy o captive portal consentono le pagine HTTPS ma bloccano le richieste di upgrade WebSocket.

Misura la velocità di download

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

console.log(speed.mbps);

Usa un tuo endpoint di file statici in modo che il risultato rifletta il percorso di rete utilizzato dalla tua app.

Stima la perdita di pacchetti

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

console.log(loss.lossPercent);

Il ping ICMP raw non è supportato nelle app per App Store e Play Store. Questo metodo misura la perdita di pacchetti a livello applicativo ripetendo i probe TCP o HTTP.

Fallback web

L'implementazione web è pensata per lo sviluppo. I browser non possono aprire socket TCP raw e i controlli URL potrebbero essere limitati da CORS. Usa build iOS o Android per una diagnostica completa.