Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Importer

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

Démarrage rapide

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

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

Exemple : testUrl

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

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

Exemple : testPort

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

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

Erreurs courantes

• Sync native : exécuter bunx cap sync après les mises à jour du plugin.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Générer un rapport de diagnostic complet

runDiagnostics est le moyen le plus rapide de collecter un rapport de support pour un utilisateur sur un réseau restreint.

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

Vérifier l'état actuel du réseau

const status = await NetworkDiagnostics.getNetworkStatus();

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

Les flags exacts dépendent de la plateforme. Android peut signaler l'état de la connexion internet validée et du portail captif. iOS expose le statut du chemin, le type d'interface, les chemins coûteux et les chemins contraints via Network.framework.

Tester la connectivité à 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);
}

Utilisez un véritable endpoint de santé de votre backend. Une vérification faite uniquement dans le navigateur peut être faussée par la WebView, le CORS, un proxy ou le comportement d'un portail captif, alors que ce plugin utilise les couches réseau natives.

Tester un port TCP

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

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

C'est utile lorsqu'un point d'accès Wi-Fi bloque les ports non standard, MQTT, des passerelles personnalisées ou un backend privé, tout en laissant la navigation normale possible.

Tester la connectivité WebSocket

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

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

À utiliser lorsque les proxys ou les portails captifs autorisent les pages HTTPS mais bloquent les requêtes de mise à niveau WebSocket.

Mesurer la vitesse de téléchargement

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

console.log(speed.mbps);

Utilisez votre propre endpoint de fichier statique pour que le résultat reflète le chemin réseau utilisé par votre application.

Estimer la perte de paquets

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

console.log(loss.lossPercent);

Le ping ICMP brut n'est pas disponible dans les applications de l'App Store et du Play Store. Cette méthode mesure la perte de paquets au niveau applicatif en répétant des sondes TCP ou HTTP.

Fallback web

L’implémentation web est destinée au développement. Les navigateurs ne peuvent pas ouvrir de sockets TCP bruts, et les vérifications d’URL peuvent être limitées par CORS. Utilisez des builds iOS ou Android pour un diagnostic réseau fiable.