Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-wifi
bunx cap sync

Importieren

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

Quickstart

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

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

Beispiel: Verbinden

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

Beispiel: Trennen

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

await CapacitorWifi.disconnect();

Häufige Stolperfallen

• Berechtigungen: aufrufen checkPermissions() dann requestPermissions() bei Bedarf.
• Listener: Handles beim Unmounten von Screens entfernen.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

API Übersicht

addNetwork

Zeigt einen Systemdialog an, um ein Wi-Fi-Netzwerk zum Gerät hinzuzufügen. Unter Android SDK 30+ öffnet dies die System-Wi-Fi-Einstellungen mit vorausgefülltem Netzwerk. Unter iOS erfolgt die direkte Verbindung zum Netzwerk.

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

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

connect

Verbindet mit einem Wi-Fi-Netzwerk. Unter Android wird eine temporäre Verbindung erstellt, die den Traffic standardmäßig nicht über das Netzwerk routet. Setze autoRouteTraffic auf true, um den App-Traffic an das verbundene Netzwerk zu binden (nützlich für lokale/gerätebasierte APs). Nutze für eine dauerhafte Verbindung unter Android stattdessen addNetwork(). Unter iOS wird eine persistente Verbindung hergestellt.

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

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

disconnect

Trennt die Verbindung zum aktuellen Wi-Fi-Netzwerk. Unter iOS werden nur Netzwerke getrennt, die über dieses Plugin hinzugefügt wurden.

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

await CapacitorWifi.disconnect();

getAvailableNetworks

Ruft eine Liste verfügbarer Wi-Fi-Netzwerke aus dem letzten Scan ab. Nur unter Android verfügbar.

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

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

getIpAddress

Die aktuelle IP-Adresse des Geräts abrufen. Verfügbar für Android und iOS.

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

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

getRssi

Ruft die aktuelle Signalstärke (RSSI) des Netzwerks in dBm ab. Nur für Android verfügbar.

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

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

getSsid

Die Service Set Identifier (SSID) des aktuellen Netzwerks abrufen. Verfügbar für Android und iOS.

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

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

getWifiInfo

Umfassende Informationen über das aktuell verbundene WiFi-Netzwerk abrufen. Diese Methode liefert detaillierte Netzwerkdaten wie SSID, BSSID, IP-Adresse, Frequenz, Übertragungsrate und Signalstärke in einem einzigen Call. Unter iOS sind einige Felder eventuell nicht verfügbar und werden undefined zurückgegeben.

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

Prüft, ob Wi-Fi auf dem Gerät aktiviert ist. Nur für Android verfügbar.

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

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

startScan

Startet den Scan nach Wi-Fi-Netzwerken. Nur für Android verfügbar. Ergebnisse werden über den ‚networksScanned‘ Event-Listener geliefert. Hinweis: Kann durch System-Throttling oder Hardware-Probleme fehlschlagen.

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

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

checkPermissions

Prüft den aktuellen Berechtigungsstatus für den Standortzugriff. Standortberechtigungen sind für Wi-Fi-Operationen auf beiden Plattformen erforderlich.

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

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

requestPermissions

Fordert den Standortzugriff beim Nutzer an. Standortberechtigungen sind für Wi-Fi-Operationen auf beiden Plattformen erforderlich.

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

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

Typreferenz

AddNetworkOptions

Optionen zum Hinzufügen eines Netzwerks.

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

Optionen zum Verbinden mit einem Netzwerk.

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

Optionen zum Trennen von einem Netzwerk.

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

GetAvailableNetworksResult

Ergebnis von getAvailableNetworks().

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

GetIpAddressResult

Ergebnis von getIpAddress().

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

GetRssiResult

Ergebnis von getRssi().

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

GetSsidResult

Ergebnis von getSsid().

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

WifiInfo

Umfassende WiFi-Informationen.

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

Ergebnis von isEnabled().

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

PermissionStatus

Berechtigungsstatus.

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

RequestPermissionsOptions

Optionen für die Berechtigungsanfrage.

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

NetworkSecurityType

Arten der Netzwerksicherheit.

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

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit Mit @capgo/capacitor-wifi für die native Funktionalität bei der Nutzung von @capgo/capacitor-wifi, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.