Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

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

Importar

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

Inicio rápido

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

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

Ejemplo: testUrl

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

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

Ejemplo: testPort

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

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

Errores comunes

• Sync nativo: ejecuta bunx cap sync tras actualizar los plugins.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Generar un reporte de diagnóstico completo

runDiagnostics es la forma más rápida de recopilar un reporte de soporte para un usuario en una red restringida.

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

Verificar el estado actual de la red

const status = await NetworkDiagnostics.getNetworkStatus();

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

Los flags exactos dependen de la plataforma. Android puede reportar el estado de internet validado y del portal cautivo. iOS reporta el estado de la ruta, el tipo de interfaz, las rutas costosas y las rutas restringidas mediante Network.framework.

Probar la conectividad de 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 endpoint de health real de tu backend. Una comprobación solo desde el navegador puede quedar oculta por el WebView, CORS, un proxy o el comportamiento del portal cautivo, mientras que este plugin usa networking nativo.

Probar un puerto TCP

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

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

Esto es útil cuando un punto de acceso Wi-Fi bloquea puertos no estándar, MQTT, gateways personalizados o un backend privado, aunque permita la navegación normal.

Probar la conectividad WebSocket

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

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

Úsalo cuando los proxies o portales cautivos permitan páginas HTTPS pero bloqueen las solicitudes de upgrade de WebSocket.

Medir la velocidad de descarga

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

console.log(speed.mbps);

Usa tu propio endpoint de archivos estáticos para que el resultado refleje la ruta de red que necesita tu app.

Estimar la pérdida de paquetes

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

console.log(loss.lossPercent);

El ping ICMP puro no es portable en apps de App Store y Play Store. Este método mide la pérdida de paquetes a nivel de aplicación repitiendo sondas TCP o HTTP.

Fallback web

La implementación web es solo para desarrollo. Los navegadores no pueden abrir sockets TCP directos y las comprobaciones de URL pueden estar limitadas por CORS. Usa builds de iOS o Android para diagnósticos de red reales.