RNWW Plugin WiFi

React Native WebView WiFi 정보 조회 및 연결 관리 플러그인

설치

npm install rnww-plugin-wifi

빠른 시작

import { registerWifiHandlers } from 'rnww-plugin-wifi';

registerWifiHandlers({
  bridge: yourBridgeImplementation,
  platform: { OS: Platform.OS },
});

Bridge Handlers

getCurrentWifiInfo

현재 연결된 WiFi 정보를 조회합니다.

const result = await bridge.call('getCurrentWifiInfo');
// {
//   success: true,
//   data: {
//     ssid: 'MyWiFi',
//     bssid: 'AA:BB:CC:DD:EE:FF',
//     rssi: -45,
//     signalLevel: 80,
//     frequency: 5180,
//     linkSpeed: 433,
//     ipAddress: '192.168.1.100',
//     isConnected: true,
//     networkId: 1,
//     security: 'WPA2'
//   }
// }

getWifiList

사용 가능한 WiFi 네트워크 목록을 스캔합니다. (Android only)

const result = await bridge.call('getWifiList');
// {
//   success: true,
//   data: [
//     {
//       ssid: 'MyWiFi',
//       bssid: 'AA:BB:CC:DD:EE:FF',
//       rssi: -45,
//       signalLevel: 80,
//       frequency: 5180,
//       security: 'WPA2',
//       channel: 36
//     },
//     ...
//   ]
// }

isWifiEnabled

WiFi 활성화 상태를 확인합니다.

const result = await bridge.call('isWifiEnabled');
// {
//   success: true,
//   isEnabled: true,
//   wifiState: 'ENABLED'
// }

connectToWifi

WiFi 네트워크에 연결합니다.

const result = await bridge.call('connectToWifi', {
  ssid: 'MyWiFi',
  password: 'mypassword',
  isHidden: false
});
// {
//   success: true,
//   wifiInfo: { ssid: 'MyWiFi', ... }
// }

disconnect

현재 WiFi 연결을 해제합니다.

const result = await bridge.call('disconnect');
// { success: true }

checkWifiPermission

WiFi 관련 권한 상태를 확인합니다.

const result = await bridge.call('checkWifiPermission');
// {
//   locationGranted: true,
//   canAccessWifiInfo: true,
//   requiredPermissions: [],
//   details: {
//     fineLocation: true,
//     coarseLocation: true
//   }
// }

requestWifiPermission

WiFi 관련 권한을 요청합니다.

const result = await bridge.call('requestWifiPermission');
// {
//   locationGranted: true,
//   canAccessWifiInfo: true,
//   requiredPermissions: []
// }

이벤트

onWifiStateChange

WiFi 상태 변경 시 이벤트를 수신합니다.

bridge.on('onWifiStateChange', (event) => {
  console.log('WiFi state changed:', event);
});

WifiStateChangeEvent 구조

interface WifiStateChangeEvent {
  type: 'WIFI_STATE_CHANGED' | 'CONNECTION_STATE_CHANGED' | 'NETWORK_INFO_CHANGED';
  wifiState?: 'DISABLED' | 'DISABLING' | 'ENABLED' | 'ENABLING' | 'UNKNOWN';
  connectionState?: 'DISCONNECTED' | 'CONNECTING' | 'CONNECTED' | 'DISCONNECTING' | 'UNKNOWN';
  wifiInfo?: WifiInfo;
  timestamp: number;
}

타입 정의

WifiInfo

interface WifiInfo {
  ssid: string | null;
  bssid: string | null;
  rssi: number | null;           // 신호 강도 (dBm)
  signalLevel: number | null;    // 신호 레벨 (0-100)
  frequency: number | null;      // 주파수 (MHz)
  linkSpeed: number | null;      // 링크 속도 (Mbps)
  ipAddress: string | null;
  isConnected: boolean;
  networkId?: number;
  security?: WifiSecurityType;
}

WifiNetwork

interface WifiNetwork {
  ssid: string;
  bssid: string;
  rssi: number;
  signalLevel: number;
  frequency: number;
  security: WifiSecurityType;
  channel?: number;
}

WifiSecurityType

type WifiSecurityType =
  | 'OPEN'
  | 'WEP'
  | 'WPA'
  | 'WPA2'
  | 'WPA3'
  | 'WPA_WPA2'
  | 'WPA2_WPA3'
  | 'UNKNOWN';

ConnectOptions

interface ConnectOptions {
  ssid: string;
  password?: string;
  security?: WifiSecurityType;
  isHidden?: boolean;
  timeout?: number;
}

PermissionStatus

interface PermissionStatus {
  locationGranted: boolean;
  canAccessWifiInfo: boolean;
  requiredPermissions: string[];
  details?: {
    fineLocation?: boolean;
    coarseLocation?: boolean;
    backgroundLocation?: boolean;
  };
}

WifiErrorCode

type WifiErrorCode =
  | 'PERMISSION_DENIED'
  | 'WIFI_DISABLED'
  | 'NETWORK_NOT_FOUND'
  | 'AUTHENTICATION_FAILED'
  | 'CONNECTION_FAILED'
  | 'TIMEOUT'
  | 'INVALID_SSID'
  | 'INVALID_PASSWORD'
  | 'NOT_SUPPORTED'
  | 'MODULE_NOT_AVAILABLE'
  | 'UNKNOWN';

권한 설정

Android

AndroidManifest.xml에 자동 추가:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Note: Android 8.0 이상에서 WiFi SSID를 가져오려면 위치 권한이 필요합니다.

iOS

Info.plist에 추가:

<key>NSLocationWhenInUseUsageDescription</key>
<string>WiFi 정보를 가져오기 위해 위치 권한이 필요합니다.</string>

Xcode에서 Signing & Capabilities에 다음 추가:

• Access WiFi Information capability

플랫폼별 제한사항

Android

• WiFi 스캔 (getWifiList)은 Android에서만 지원됩니다.
• Android 10 이상에서는 WiFi 연결 시 시스템 UI가 표시됩니다.
• Android 10 미만에서는 레거시 방식으로 연결됩니다.

iOS

• WiFi 스캔 (getWifiList)은 iOS에서 지원되지 않습니다.
• WiFi 연결은 iOS 11 이상에서만 지원됩니다.
• RSSI, frequency, linkSpeed 등 일부 정보는 iOS에서 제공되지 않습니다.
• WiFi 정보 접근을 위해 Access WiFi Information entitlement가 필요합니다.

예제

WiFi 정보 표시

async function showWifiInfo() {
  // 권한 확인
  const permission = await bridge.call('checkWifiPermission');
  if (!permission.canAccessWifiInfo) {
    await bridge.call('requestWifiPermission');
  }

  // WiFi 정보 조회
  const result = await bridge.call('getCurrentWifiInfo');
  if (result.success && result.data) {
    console.log(`Connected to: ${result.data.ssid}`);
    console.log(`Signal: ${result.data.signalLevel}%`);
    console.log(`IP: ${result.data.ipAddress}`);
  }
}

WiFi 연결

async function connectWifi(ssid: string, password: string) {
  const result = await bridge.call('connectToWifi', {
    ssid,
    password
  });

  if (result.success) {
    console.log('Connected successfully!');
  } else {
    console.error(`Connection failed: ${result.error}`);
  }
}

상태 변경 모니터링

bridge.on('onWifiStateChange', (event) => {
  switch (event.type) {
    case 'WIFI_STATE_CHANGED':
      console.log(`WiFi state: ${event.wifiState}`);
      break;
    case 'CONNECTION_STATE_CHANGED':
      console.log(`Connection: ${event.connectionState}`);
      if (event.wifiInfo) {
        console.log(`SSID: ${event.wifiInfo.ssid}`);
      }
      break;
  }
});

라이선스

MIT