시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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

가져오기

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

빠른 시작

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

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

예시: testUrl

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

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

예시: testPort

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

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

자주 하는 실수

• 네이티브 동기화: 실행 bunx cap sync 플러그인 업그레이드 후.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

전체 진단 보고서 실행

runDiagnostics 제한된 네트워크 환경의 사용자로부터 지원 보고서를 수집하는 가장 빠른 방법입니다.

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

현재 네트워크 상태 확인

const status = await NetworkDiagnostics.getNetworkStatus();

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

플랫폼에 따라 사용 가능한 플래그가 다릅니다. Android는 검증된 인터넷 연결 및 캡티브 포털(captive portal) 상태를 보고할 수 있습니다. iOS는 경로 상태, 인터페이스 유형, 비용이 많이 드는 경로(expensive paths) 및 제한된 경로(constrained paths)를 보고합니다. Network.framework.

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

백엔드의 실제 헬스 체크(health) 엔드포인트를 사용하세요. 브라우저 기반 체크는 WebView, CORS, 프록시 또는 캡티브 포털 동작에 의해 가려질 수 있지만, 이 플러그인은 네이티브 네트워킹을 사용합니다.

TCP 포트 테스트

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

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

일반적인 웹 브라우징은 허용하면서 비표준 포트, MQTT, 커스텀 게이트웨이 또는 프라이빗 백엔드를 차단하는 Wi-Fi 액세스 포인트가 있는 경우 유용합니다.

WebSocket 연결 테스트

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

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

프록시나 캡티브 포털이 HTTPS 페이지는 허용하지만 WebSocket 업그레이드 요청은 차단할 때 사용하세요.

다운로드 속도 측정

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

console.log(speed.mbps);

결과가 앱에 필요한 네트워크 경로를 반영하도록 자체 정적 파일 엔드포인트를 사용하세요.

패킷 손실 추정

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

console.log(loss.lossPercent);

App Store 및 Play Store 앱에서는 Raw ICMP ping을 사용할 수 없습니다. 이 방법은 TCP 또는 HTTP 프로브를 반복해 애플리케이션 레벨의 패킷 손실을 측정합니다.

웹 fallback

웹 구현 버전은 개발용입니다. 브라우저는 raw TCP 소켓을 열 수 없으며, URL 체크는 CORS 제한을 받을 수 있습니다. 실제 네트워크 진단 기능을 사용하려면 iOS 또는 Android Native Build를 이용하세요.