@capawesome-team/capacitor-wifi¶

Capacitor plugin to manage Wi-Fi connectivity.

Features¶

🖥️ Cross-platform: Supports Android and iOS.
🌐 Network Management: Connect and disconnect networks.
🔍 Network Scan: Perform scans for available networks.
📟 Device Info: Retrieve essential device information like IP address.
🔁 Up-to-date: Always supports the latest Capacitor version.
⭐️ Support: First-class support from the Capawesome Team.

Installation¶

This plugin is only available to Capawesome Insiders. First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Attention: Replace <YOUR_LICENSE_KEY> with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a Capawesome Insider.

Next, install the package:

npm install @capawesome-team/capacitor-wifi
npx cap sync

Android¶

Permissions¶

This API requires the following permissions be added to your AndroidManifest.xml before or after the application tag:

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

iOS¶

Entitlements¶

Ensure Access Wi-Fi Information and Hotspot capabilities have been enabled in your application in Xcode. See Add a capability to a target for more information.

Privacy Descriptions¶

Add the NSLocationWhenInUseUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription keys to the ios/App/App/Info.plist file, which tells the user why your app is requesting location information:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to request Wi-Fi information.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need your location to request Wi-Fi information.</string>

Configuration¶

Prop	Type	Description	Default	Since
`useWifiManager`	`boolean`	Whether or not to use the deprecated `WifiManager` API for connecting to Wi-Fi networks. Only available on Android.	`false`	6.3.0

Examples¶

In capacitor.config.json:

{
  "plugins": {
    "Wifi": {
      "useWifiManager": undefined
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capawesome-team/capacitor-wifi" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Wifi: {
      useWifiManager: undefined,
    },
  },
};

export default config;

Demo¶

A working example can be found here: robingenz/capacitor-plugin-demo

Usage¶

import { Wifi } from '@capawesome-team/capacitor-wifi';

const connect = async () => {
    await Wifi.connect({
        ssid: 'MyNetwork',
        password: 'MyPassword',
        isHiddenSsid: false
    });
}

const disconnect = async () => {
    await Wifi.disconnect();
}

const getAvailableNetworks = async () => {
    const result = await Wifi.getAvailableNetworks();
    return result.networks;
}

const getIpAddress = async () => {
    const result = await Wifi.getIpAddress();
    return result.address;
}

const getRssi = async () => {
    const result = await Wifi.getRssi();
    return result.rssi;
}

const getSsid = async () => {
    const result = await Wifi.getSsid();
    return result.ssid;
}

const isEnabled = async () => {
    const result = await Wifi.isEnabled();
    return result.enabled;
}

const startScan = async () => {
    await Wifi.startScan();
}

connect(...)¶

connect(options: ConnectOptions) => Promise<void>

Connect to a Wi-Fi network.

Only available on Android and iOS.

Param	Type
`options`	`ConnectOptions`

Since: 6.0.0

disconnect(...)¶

disconnect(options?: DisconnectOptions | undefined) => Promise<void>

Disconnect from a Wi-Fi network.

On iOS, you can only disconnect from networks that you connected to using the plugin. This also removes the Wi-Fi network from the list of known networks.

Only available on Android and iOS.

Param	Type
`options`	`DisconnectOptions`

Since: 6.0.0

getAvailableNetworks()¶

getAvailableNetworks() => Promise<GetAvailableNetworksResult>

Get a list of Wi-Fi networks found during the last scan.

The returned networks are the most recently updated results, which may be from a previous scan if your current scan has not completed or succeeded.

Only available on Android.

Returns: Promise<GetAvailableNetworksResult>

Since: 6.0.0

getIpAddress()¶

getIpAddress() => Promise<GetIpAddressResult>

Get the current IP address of the device.

Only available on Android and iOS.

Returns: Promise<GetIpAddressResult>

Since: 6.0.0

getRssi()¶

getRssi() => Promise<GetRssiResult>

Get the received signal strength indicator (RSSI) of the current network in dBm.

Only available on Android.

Returns: Promise<GetRssiResult>

Since: 6.0.0

getSsid()¶

getSsid() => Promise<GetSsidResult>

Get the service set identifier (SSID) of the current network.

Only available on Android and iOS.

Returns: Promise<GetSsidResult>

Since: 6.0.0

isEnabled()¶

isEnabled() => Promise<IsEnabledResult>

Check if Wi-Fi is enabled.

Only available on Android.

Returns: Promise<IsEnabledResult>

Since: 6.0.0

startScan()¶

startScan() => Promise<void>

Start a scan for Wi-Fi networks.

This call may fail for any of the following reasons: - Scan requests may be throttled because of too many scans in a short time. - The device is idle and scanning is disabled. - Wi-Fi hardware reports a scan failure.

Only available on Android.

Since: 6.0.0

checkPermissions()¶

checkPermissions() => Promise<PermissionStatus>

Check permissions for the plugin.

Only available on Android and iOS.

Returns: Promise<PermissionStatus>

Since: 6.0.0

requestPermissions(...)¶

requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>

Request permissions for the plugin.

Only available on Android and iOS.

Param	Type
`options`	`RequestPermissionsOptions`

Returns: Promise<PermissionStatus>

Since: 6.0.0

addListener('networksScanned', ...)¶

addListener(eventName: 'networksScanned', listenerFunc: (event: NetworksScannedEvent) => void) => Promise<PluginListenerHandle>

Called when the scan results are available.

Only available on Android.

Param	Type
`eventName`	`'networksScanned'`
`listenerFunc`	`(event: NetworksScannedEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 6.0.0

removeAllListeners()¶

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 6.0.0

Interfaces¶

ConnectOptions¶

Prop	Type	Description	Default	Since
`ssid`	`string`	The SSID of the network to connect to.
`password`	`string`	The password of the network to connect to.		6.0.0
`isHiddenSsid`	`boolean`	Whether or not the SSID is hidden. Only available on Android.	`false`	6.0.0

DisconnectOptions¶

Prop	Type	Description	Since
`ssid`	`string`	The SSID of the network to disconnect from. If not provided, the device will disconnect from the current network. Only available on iOS.	6.0.0

GetAvailableNetworksResult¶

Prop	Type	Description	Since
`networks`	`Network[]`	The list of Wi-Fi networks found during the last scan.	6.0.0

Network¶

Prop	Type	Description	Since
`rssi`	`number`	The received signal strength indicator (RSSI) of the network in dBm.	6.1.0
`securityTypes`	`NetworkSecurityType[]`	The service set identifier (SSID) of the network. Only available on Android (SDK 33+).	6.1.0
`ssid`	`string`	The service set identifier (SSID) of the network.	6.0.0

GetIpAddressResult¶

Prop	Type	Description	Since
`address`	`string`	The IP address of the device.	6.0.0

GetRssiResult¶

Prop	Type	Description	Since
`rssi`	`number`	The received signal strength indicator (RSSI) of the current network in dBm.	6.0.0

GetSsidResult¶

Prop	Type	Description	Since
`ssid`	`string`	The service set identifier (SSID) of the current network. On iOS 14+, the SSID can only be retrieved if the network was connected to using the plugin or if the app has permission to access precise location.	6.0.0

IsEnabledResult¶

Prop	Type	Description	Since
`enabled`	`boolean`	Whether or not Wi-Fi is enabled.	6.0.0

PermissionStatus¶

Prop	Type	Since
`location`	`PermissionState`	6.0.0

RequestPermissionsOptions¶

Prop	Type	Description	Default	Since
`permissions`	`'location'[]`	The permissions to request.	`["location"]`	6.0.0

PluginListenerHandle¶

Prop	Type
`remove`	`() => Promise<void>`

NetworksScannedEvent¶

Prop	Type	Description	Since
`networks`	`Network[]`	The list of Wi-Fi networks found during the scan.	6.0.0

Type Aliases¶

PermissionState¶

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

PermissionType¶

'location'

Enums¶

NetworkSecurityType¶

Members	Value	Description	Since
`UNKNOWN`	`-1`	Unknown security type.	6.1.0
`OPEN`	`0`	Open network.	6.1.0
`WEP`	`1`	WEP network.	6.1.0
`PSK`	`2`	PSK network.	6.1.0
`EAP`	`3`	EAP network.	6.1.0
`SAE`	`4`	SAE network.	6.1.0
`EAP_WPA3_ENTERPRISE_192_BIT`	`5`	WPA3-Enterprise in 192-bit security network.	6.1.0
`OWE`	`6`	OWE network.	6.1.0
`WAPI_PSK`	`7`	WAPI PSK network.	6.1.0
`WAPI_CERT`	`8`	WAPI Certificate network.	6.1.0
`WPA3_ENTERPRISE`	`9`	WPA3-Enterprise network.	6.1.0
`OSEN`	`10`	OSEN network.	6.1.0
`PASSPOINT_R1_R2`	`11`	Passpoint R1/R2 network, where TKIP and WEP are not allowed.	6.1.0
`PASSPOINT_R3`	`12`	Passpoint R3 network, where TKIP and WEP are not allowed, and PMF must be set to Required.	6.1.0
`DPP`	`13`	Easy Connect (DPP) network.	6.1.0

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.