Capacitor 앱에서 네트워크 상태를 감지하는 방법

Capacitor 앱에서 네트워크 상태를 감지하려면 설치 @capacitor/network, Network.getStatus() 현재 상태를 호출하고, 구독 networkStatusChange 업데이트를 위해. 이는 장치가 연결되어 있는지 여부와 Wi-Fi 또는 셀룰러 연결인지 여부를 알려줍니다. 인터넷이 실제로 작동하는지, 또는 연결이 측정되는지 여부를 알기 위해서는 네트워크 접근 가능성 확인을 추가하거나 @capgo/capacitor-network-diagnostics이 안내서에서는 Capacitor 8 code까지 모든 세 가지 층을 다룹니다.

‘사용자가 온라인인지?’라는 질문의 뒤에 있는 세 가지 질문입니다.

대부분의 오프라인 버그는 첫 번째 행을 세 번째 행으로 처리하는 것입니다. 호텔 Wi-Fi에 로그인 페이지가 있는 경우 connected: true API 호출이 모두 시간 초과되었습니다.

네트워크 플러그인을 설치하세요.

bun add @capacitor/network
bunx cap sync

설정이 필요하지 않습니다. 안드로이드에서는 플러그인이 설치 시에 정상적인 권한을 부여하며, iOS에서는 아무것도 필요하지 않습니다. ACCESS_NETWORK_STATE 현재 상태를 읽어보세요.

앱이 시작될 때 캐시 또는 네트워크에서 로드하기 전에 호출하세요. 몇 밀리초 안에 OS 상태를 읽기 때문에 트래픽을 보내지 않습니다.

import { Network } from '@capacitor/network';

const status = await Network.getStatus();
console.log(status.connected);      // true or false
console.log(status.connectionType); // 'wifi' | 'cellular' | 'none' | 'unknown'

네트워크 변경을 듣보세요.

두 가지 실용적인 점:

import { Network, type ConnectionStatus } from '@capacitor/network';
import type { PluginListenerHandle } from '@capacitor/core';

let handle: PluginListenerHandle | undefined;

export async function watchNetwork(onChange: (s: ConnectionStatus) => void) {
  onChange(await Network.getStatus());
  handle = await Network.addListener('networkStatusChange', onChange);
}

export async function stopWatchingNetwork() {
  await handle?.remove();
}

두 가지 실용적인 정보

• __CAPGO_KEEP_0__ 이벤트를 지연 처리하세요. none Wi-Fi에서 셀룰러로 전환할 때, 두 플랫폼 모두 새로운 링크가 준비되기 전에 잠시 동안 연결을 보고할 수 있습니다. 1초에서 2초의 지연 시간을 두고 '오프라인' 배너를 표시하면 깜빡임을 피할 수 있습니다.
• 리스너를 제거하세요. 컴포넌트가 언마운트될 때 리스너를 제거하지 않으면,热 재로드와 네비게이션 후 callback을 여러 번 호출할 수 있습니다.

React 훅

import { useEffect, useState } from 'react';
import { Network, type ConnectionStatus } from '@capacitor/network';

export function useNetworkStatus() {
  const [status, setStatus] = useState<ConnectionStatus>({ connected: true, connectionType: 'unknown' });

  useEffect(() => {
    let timer: ReturnType<typeof setTimeout>;
    const listener = Network.addListener('networkStatusChange', (s) => {
      clearTimeout(timer);
      timer = setTimeout(() => setStatus(s), s.connected ? 0 : 1500);
    });
    Network.getStatus().then(setStatus);
    return () => {
      clearTimeout(timer);
      listener.then((l) => l.remove());
    };
  }, []);

  return status;
}

온라인으로 연결되는 것은 즉시 적용되지만 오프라인 상태는 1.5초 후에 적용됩니다. Vue composable이나 Angular 서비스와 같은 동일한 패턴이 작동합니다. BehaviorSubject.

왜 '연결'이 온라인이 아님에 대한 이유

connected: true 이것은 OS 네트워크 스택에서 오는 것입니다. 다음이 참인 경우:

• Wi-Fi 네트워크에 캡티브 게이트웨이가 있으면(공항, 호텔, 기차 등)
• 라우터에 업스트림 연결이 없으면
• DNS가 깨끗하지 않거나 필터링되면
• 기업 방화벽 또는 VPN이 API 도메인을 차단합니다.
• __CAPGO_KEEP_0__ 도메인에 대한 액세스 권한이 없습니다.

해결책은 __CAPGO_KEEP_0__ 도메인에 대한 접근 가능성을 확인하는 것입니다:

export async function canReachApi(timeoutMs = 4000): Promise<boolean> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const res = await fetch('https://api.example.com/health', {
      method: 'HEAD',
      cache: 'no-store',
      signal: controller.signal,
    });
    return res.ok;
  } catch {
    return false;
  } finally {
    clearTimeout(timer);
  }
}

__CAPGO_KEEP_0__ 앱이 시작될 때 실행하고 networkStatusChange 보고서를 확인하고 connected: true요청이 실패할 때 실행하지 마십시오. 단기적으로는 poll을 실행하여 배터리와 데이터를 소모하지 마십시오. __CAPGO_KEEP_0__ 도메인에 대한 CORS 허용을 확인하여 __CAPGO_KEEP_0__ 앱의 출처를 허용하거나capacitor://localhost iOS에서 https://localhost 네트워크 상태를 확인하는 방법 CapacitorHttp to send it from native code.

OS에서 __CAPGO_KEEP_0__ 도메인에 대한 접근 가능성을 확인하는 방법은 다음과 같습니다.

@capgo/capacitor-network-diagnostics __CAPGO_KEEP_0__ 앱의 네트워크 상태를 더 자세히 확인하려면 OS가 알고 있는 정보를 읽고 native 체크를 실행하여 WebView CORS를 우회하십시오:

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

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

const status = await NetworkDiagnostics.getNetworkStatus();
// {
//   connected: true,
//   connectionType: 'wifi' | 'cellular' | 'ethernet' | 'vpn' | 'other' | 'unknown' | 'none',
//   internetReachable: true,
//   expensive: false,      // metered / cellular
//   constrained: false,    // iOS Low Data Mode
//   captivePortal: false,  // Android only
//   details: { ... }
// }

__CAPGO_KEEP_0__ 도메인에 대한 OS의 접근 가능성을 확인하는 방법은 다음과 같습니다.

안드로이드에서 internetReachable 네트워크 상태를 감지하는 방법은 OS가 이미 연결을 테스트했기 때문에 iOS에서는 더 강한 신호입니다. connectedHTTP 체크를 중요 흐름에 대해 유지하세요.

네트워크 상태 감지

const api = await NetworkDiagnostics.testUrl({
  url: 'https://api.example.com/health',
  method: 'HEAD',
  timeoutMs: 4000,
});
// api.reachable, api.statusCode, api.durationMs, api.errorCode

const socket = await NetworkDiagnostics.testWebSocket({ url: 'wss://realtime.example.com' });
const port = await NetworkDiagnostics.testPort({ host: 'mqtt.example.com', port: 8883 });

네이티브 요청은 CORS의 영향을 받지 않으므로, 제 3 자 호스트도 테스트할 수 있습니다.

네트워크 상태를 감지하는 방법

사용자가 "앱이 작동하지 않습니다"라고 말할 때, 1개의 탭으로 디아그노스틱 리포트를 생성하여 시간을 절약할 수 있습니다.

const report = await NetworkDiagnostics.runDiagnostics({
  urls: [{ url: 'https://api.example.com/health' }, { url: 'https://cdn.example.com/ping' }],
  websockets: [{ url: 'wss://realtime.example.com' }],
  download: { url: 'https://cdn.example.com/1mb.bin', maxBytes: 1_048_576 },
  packetLoss: { url: 'https://api.example.com/health', count: 5 },
});

console.log(report.issues);        // human-readable list of problems
console.log(report.download?.mbps);
console.log(report.packetLoss?.lossPercent);

JSON을 지원 티켓에 첨부하세요. 문제가 DNS, WebSocket이 차단된 것, 캡티브 포털, 또는 느린 연결인지 바로 알 수 있습니다.

네트워크 상태를 감지하는 방법

네트워크 상태를 감지하는 방법은 리뷰에서 빠른 승리입니다.

export async function shouldPrefetchMedia() {
  const s = await NetworkDiagnostics.getNetworkStatus();
  if (!s.connected) return false;
  if (s.constrained) return false; // user asked iOS to save data
  if (s.expensive) return false;   // cellular or metered Wi-Fi
  return true;
}

네트워크 상태를 감지하여 비디오 자동 재생, 이미지 품질, 배경 동기화 및 큰 다운로드를 결정하세요. 안드로이드에서는 사용자가 Wi-Fi 네트워크를 요금제로 표시할 수 있으므로 Wi-Fi가 무료라고 가정하지 마세요.

네트워크 상태를 감지하는 방법

A 작은 배너는 요청이 실패하는 것보다 더 명확합니다. 위의 hook을 사용하세요:

export function OfflineBanner() {
  const { connected } = useNetworkStatus();
  if (connected) return null;
  return (
    <div role="status" aria-live="polite" className="offline-banner">
      You are offline. Changes will sync when you reconnect.
    </div>
  );
}

role="status" with aria-live="polite" screen reader가 변경을 발표합니다. 프레임워크별 UI에 대한 자세한 내용은 Vue, Angular 및 React에서 오프라인 화면을 구축하는 가이드를 참조하세요. Queue work while offline.

오프라인 지원의 반은 감지뿐입니다. 상태가 오프라인이 될 때:

Serve는 로컬 스토리지에서 읽습니다. SQLite 데이터베이스와 같은

1. 대용량 데이터셋을 처리하는 데 더 좋습니다. @capgo/capacitor-fast-sql 사용자 동작을 타임스탬프와 idempotency 키와 함께 아웃박스 테이블에 기록하세요. localStorage.
2. On
3. 연결된 상태에서 networkStatusChange , 그리고 아웃박스를 순서대로 비우세요. canReachApi()protectedTokens
4. __CAPGO_KEEP_0__

재시도 실패한 요청을 지연 시간 지연으로 몇 분 이내로 제한하여 다시 시도하십시오. fetch.

앱이 종료된 후에도 업로드가 살아남아야 하는 경우 Native 업로더에 업로드를 넘겨주십시오.

@capacitor/network Web fallback navigator.onLine 그리고 online 기반되어 있습니다. offline 이벤트가 발생한다는 것은 code이 작동 중입니다. bun run dev 그것은 connectionType 그것은 unknown 그것은 navigator.connection exposes effectiveType 기반되어 있습니다. saveData, Safari는 지원하지 않으므로 옵션 힌트로 처리합니다.

문제 해결

iOS 시뮬레이터에서 리스너는 절대 동작하지 않습니다.: 시뮬레이터는 맥의 네트워크를 공유합니다. 맥의 Wi-Fi를 켜거나 항공 모드가 켜진 기기에서 테스트하세요.

connectionType 네트워크 unknown VPN: wifi, cellular, none and unknown및 vpn and ethernet.

디버그 플러그인을 사용하세요. 디버그 플러그인은앱이 네트워크를 전환할 때 1초 동안 오프라인으로 표시됩니다.

장치에서 건강 검사 실패하지만 브라우저에서 작동합니다.: CORS 허용 capacitor://localhost 그리고 https://localhost, 또는 사용 NetworkDiagnostics.testUrl, native로 실행됩니다.

navigator.onLine 플러그인이 오프라인이라고 말하는 동안 true입니다.: 플러그인을 신뢰하십시오. 일부 Android WebViews는 신뢰할 수 없습니다. navigator.onLine 공격적인 핫픽스를 공유하십시오.

오프라인 처리는 주로 자바스크립트: 임계값, 배너, 다시 시도 로직, 캐시 규칙입니다.

__CAPGO_KEEP_0__ Live Update와 함께, 사용자별로 같은 날에 그들을 조정할 수 있습니다. Capgo 다운로드는 배경에서 업데이트 패키지를 다운로드하고 다운로드가 실패하면 현재 버전을 유지하므로 나쁜 연결로 인해 사용자가 반영구적으로 설치된 업데이트 없이 남아 있지 않습니다., you can tune those for every user the same day. Capgo downloads update bundles in the background and keeps the current version if a download fails, so a bad connection never leaves users with a half-installed update. The 네트워크 진단 문서 모든 옵션 목록