시작하기

설치

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-wifi` plugin in my project.

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

bun add @capgo/capacitor-wifi
bunx cap sync

가져오기

import { CapacitorWifi } from '@capgo/capacitor-wifi';

빠른 시작

import { CapacitorWifi, NetworkSecurityType } from '@capgo/capacitor-wifi';

await CapacitorWifi.addNetwork({
  ssid: 'MyNetwork',
  password: 'mypassword',
  isHiddenSsid: false,
  securityType: NetworkSecurityType.WPA2_PSK
});

예제: 연결

import { CapacitorWifi, WifiConnectionErrorCode } from '@capgo/capacitor-wifi';

try {
  await CapacitorWifi.connect({
    ssid: 'MyNetwork',
    password: 'mypassword',
    autoRouteTraffic: true, // Android only
    timeoutMs: 30000,
  });
} catch (error: any) {
  switch (error.code) {
    case WifiConnectionErrorCode.WIFI_DISABLED:
      // Ask the user to enable Wi-Fi
      break;
    case WifiConnectionErrorCode.PERMISSION_DENIED:
      // Request the required permission
      break;
    default:
      // Generic connection error
      break;
  }
}

예제: 연결 해제

import { CapacitorWifi } from '@capgo/capacitor-wifi';

await CapacitorWifi.disconnect();

자주 하는 실수

• 권한: 호출 checkPermissions() 그 다음 requestPermissions() 필요할 때마다.
• 리스너: 화면이 unmount될 때 핸들을 제거하세요.
• 신뢰할 수 있는 단일 소스(Source of truth): 신뢰 src/definitions.ts GitHub 레포지토리에서.

API 개요

addNetwork

기기에 Wi-Fi 네트워크를 추가하는 시스템 대화 상자를 표시합니다. Android SDK 30+ 버전에서는 네트워크 정보가 미리 입력된 상태로 시스템 Wi-Fi 설정이 열립니다. iOS에서는 해당 네트워크에 직접 연결합니다.

import { CapacitorWifi, NetworkSecurityType } from '@capgo/capacitor-wifi';

await CapacitorWifi.addNetwork({
  ssid: 'MyNetwork',
  password: 'mypassword',
  isHiddenSsid: false,
  securityType: NetworkSecurityType.WPA2_PSK
});

connect

Wi-Fi 네트워크에 연결합니다. Android에서는 기본적으로 네트워크를 통해 트래픽을 라우팅하지 않는 임시 연결을 생성합니다. 연결된 네트워크로 앱 트래픽을 바인딩하려면 autoRouteTraffic을 true로 설정하세요(로컬/기기 호스트 AP 사용 시 유용). Android에서 지속적인 연결이 필요한 경우 addNetwork()를 대신 사용하세요. iOS에서는 지속적인 연결을 생성합니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

await CapacitorWifi.connect({
  ssid: 'MyNetwork',
  password: 'mypassword',
  autoRouteTraffic: true // Android only: route app traffic through this network
});

disconnect

현재 Wi-Fi 네트워크에서 연결을 해제합니다. iOS에서는 이 플러그인을 통해 추가된 네트워크만 연결이 해제됩니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

await CapacitorWifi.disconnect();

getAvailableNetworks

마지막 스캔 결과에서 사용 가능한 Wi-Fi 네트워크 목록을 가져옵니다. Android에서만 사용할 수 있습니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { networks } = await CapacitorWifi.getAvailableNetworks();
networks.forEach(network => {
  console.log(`SSID: ${network.ssid}, Signal: ${network.rssi} dBm`);
});

getIpAddress

기기의 현재 IP 주소를 가져옵니다. Android와 iOS 모두 지원합니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { ipAddress } = await CapacitorWifi.getIpAddress();
console.log('IP Address:', ipAddress);

getRssi

현재 네트워크의 수신 신호 강도 지표(RSSI)를 dBm 단위로 가져옵니다. Android에서만 사용할 수 있습니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { rssi } = await CapacitorWifi.getRssi();
console.log('Signal strength:', rssi, 'dBm');

getSsid

현재 네트워크의 SSID(Service Set Identifier)를 가져옵니다. Android와 iOS 모두 지원합니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { ssid } = await CapacitorWifi.getSsid();
console.log('Connected to:', ssid);

getWifiInfo

현재 연결된 WiFi 네트워크에 대한 상세 정보를 가져옵니다. 이 메서드는 단 한 번의 호출로 SSID, BSSID, IP 주소, 주파수, 링크 속도, 신호 강도를 포함한 상세 네트워크 정보를 제공합니다. iOS에서는 일부 필드를 사용할 수 없으며 undefined로 반환될 수 있습니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const info = await CapacitorWifi.getWifiInfo();
console.log('Network:', info.ssid);
console.log('BSSID:', info.bssid);
console.log('IP:', info.ip);
console.log('Frequency:', info.frequency, 'MHz');
console.log('Speed:', info.linkSpeed, 'Mbps');
console.log('Signal:', info.signalStrength);

isEnabled

기기의 Wi-Fi 활성화 여부를 확인합니다. Android에서만 사용할 수 있습니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { enabled } = await CapacitorWifi.isEnabled();
console.log('WiFi is', enabled ? 'enabled' : 'disabled');

startScan

Wi-Fi 네트워크 스캔을 시작합니다. Android에서만 사용할 수 있습니다. 결과는 ‘networksScanned’ 이벤트 리스너를 통해 전달됩니다. 참고: 시스템 스로틀링 또는 하드웨어 문제로 인해 실패할 수 있습니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

await CapacitorWifi.addListener('networksScanned', () => {
  console.log('Scan completed');
});
await CapacitorWifi.startScan();

checkPermissions

현재 위치 권한 상태를 확인합니다. 두 플랫폼 모두 Wi-Fi 동작을 위해 위치 권한이 필요합니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const status = await CapacitorWifi.checkPermissions();
console.log('Location permission:', status.location);

requestPermissions

사용자에게 위치 권한을 요청합니다. 두 플랫폼 모두 Wi-Fi 동작을 위해 위치 권한이 필요합니다.

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const status = await CapacitorWifi.requestPermissions();
if (status.location === 'granted') {
  console.log('Permission granted');
}

타입 레퍼런스

AddNetworkOptions

네트워크 추가를 위한 옵션입니다.

export interface AddNetworkOptions {
  /**
   * The SSID of the network to add
   *
   * @since 7.0.0
   */
  ssid: string;

  /**
   * The password for the network (optional for open networks)
   *
   * @since 7.0.0
   */
  password?: string;

  /**
   * Whether the network is hidden (Android only)
   *
   * @since 7.0.0
   * @default false
   */
  isHiddenSsid?: boolean;

  /**
   * The security type of the network (Android only)
   *
   * @since 7.0.0
   * @default NetworkSecurityType.WPA2_PSK
   */
  securityType?: NetworkSecurityType;
}

ConnectOptions

네트워크 연결을 위한 옵션입니다.

export interface ConnectOptions {
  /**
   * The SSID of the network to connect to
   *
   * @since 7.0.0
   */
  ssid: string;

  /**
   * The password for the network (optional for open networks)
   *
   * @since 7.0.0
   */
  password?: string;

  /**
   * Whether the network is hidden (Android only)
   *
   * @since 7.0.0
   * @default false
   */
  isHiddenSsid?: boolean;

  /**
   * Whether to automatically route app traffic through the connected Wi-Fi network (Android only)
   * When enabled, it binds the app process to the connected network using ConnectivityManager.bindProcessToNetwork()
   * This is useful for connecting to local/device-hosted APs (e.g., ESP32, IoT devices) that don't have internet access.
   *
   * @since 7.0.0
   * @default false
   */
  autoRouteTraffic?: boolean;
}

DisconnectOptions

네트워크 연결 해제를 위한 옵션입니다.

export interface DisconnectOptions {
  /**
   * The SSID of the network to disconnect from (optional)
   *
   * @since 7.0.0
   */
  ssid?: string;
}

GetAvailableNetworksResult

getAvailableNetworks()의 결과값.

export interface GetAvailableNetworksResult {
  /**
   * List of available networks
   *
   * @since 7.0.0
   */
  networks: Network[];
}

GetIpAddressResult

getIpAddress()의 결과값.

export interface GetIpAddressResult {
  /**
   * The device's IP address
   *
   * @since 7.0.0
   */
  ipAddress: string;
}

GetRssiResult

getRssi()의 결과값.

export interface GetRssiResult {
  /**
   * The signal strength in dBm
   *
   * @since 7.0.0
   */
  rssi: number;
}

GetSsidResult

getSsid()의 결과값.

export interface GetSsidResult {
  /**
   * The SSID of the current network
   *
   * @since 7.0.0
   */
  ssid: string;
}

WifiInfo

상세한 WiFi 정보.

export interface WifiInfo {
  /**
   * The SSID (network name) of the current network
   *
   * @since 7.0.0
   */
  ssid: string;

  /**
   * The BSSID (MAC address) of the access point.
   * Not available on iOS.
   *
   * @since 7.0.0
   */
  bssid?: string;

  /**
   * The device's IP address on the network
   *
   * @since 7.0.0
   */
  ip: string;

  /**
   * The network frequency in MHz.
   * Not available on iOS.
   *
   * @since 7.0.0
   */
  frequency?: number;

  /**
   * The connection speed in Mbps.
   * Not available on iOS.
   *
   * @since 7.0.0
   */
  linkSpeed?: number;

  /**
   * The signal strength (0-100).
   * Calculated from RSSI on Android.
   * Not available on iOS.
   *
   * @since 7.0.0
   */
  signalStrength?: number;
}

IsEnabledResult

isEnabled()의 결과값.

export interface IsEnabledResult {
  /**
   * Whether Wi-Fi is enabled
   *
   * @since 7.0.0
   */
  enabled: boolean;
}

PermissionStatus

권한 상태.

export interface PermissionStatus {
  /**
   * Location permission state
   *
   * @since 7.0.0
   */
  location: PermissionState;
}

RequestPermissionsOptions

권한 요청 옵션.

export interface RequestPermissionsOptions {
  /**
   * Permissions to request
   *
   * @since 7.0.0
   */
  permissions?: 'location'[];
}

NetworkSecurityType

네트워크 보안 유형

export enum NetworkSecurityType {
  /**
   * Open network with no security
   *
   * @since 7.0.0
   */
  OPEN = 0,

  /**
   * WEP security
   *
   * @since 7.0.0
   */
  WEP = 1,

  /**
   * WPA/WPA2 Personal (PSK)
   *
   * @since 7.0.0
   */
  WPA2_PSK = 2,

  /**
   * WPA/WPA2/WPA3 Enterprise (EAP)
   *
   * @since 7.0.0
   */
  EAP = 3,

  /**
   * WPA3 Personal (SAE)
   *
   * @since 7.0.0
   */
  SAE = 4,

  /**
   * WPA3 Enterprise
   *
   * @since 7.0.0
   */
  WPA3_ENTERPRISE = 5,

  /**
   * WPA3 Enterprise 192-bit mode
   *
   * @since 7.0.0
   */
  WPA3_ENTERPRISE_192_BIT = 6,

  /**
   * Passpoint network
   *
   * @since 7.0.0
   */
  PASSPOINT = 7,

  /**
   * Enhanced Open (OWE)
   *
   * @since 7.0.0
   */
  OWE = 8,

  /**
   * WAPI PSK
   *
   * @since 7.0.0
   */
  WAPI_PSK = 9,

  /**
   * WAPI Certificate
   *
   * @since 7.0.0
   */
  WAPI_CERT = 10,
}

Source of Truth

이 페이지는 플러그인의 src/definitions.ts에서 생성되었습니다. 상위의 API가 변경되면 다시 sync를 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-wifi 사용하기 @capgo/capacitor-wifi 사용 시의 Native 기능은, API 개요 API 개요의 구현 상세 내용은, 소개 Introduction의 구현 상세 내용은, API 키 API Keys의 구현 상세 내용은, 기기 Devices의 구현 상세 내용은.