Premiers pas

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez la configuration manuelle, installez le plugin avec les commandes suivantes, puis suivez les instructions spécifiques à chaque plateforme ci-dessous :

bun add @capgo/capacitor-wifi
bunx cap sync

Importer

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

Démarrage rapide

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

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

Exemple : se connecter

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

Exemple : se déconnecter

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

await CapacitorWifi.disconnect();

Erreurs courantes

• Autorisations: appeler checkPermissions() puis requestPermissions() lorsque nécessaire.
• Écouteurs : supprimez les handles lors du démontage des écrans.
• Source de vérité: confiance src/definitions.ts dans le repo GitHub.

Aperçu de API

addNetwork

Affiche une boîte de dialogue système pour ajouter un réseau Wi-Fi à l'appareil. Sur Android SDK 30+, cela ouvre les paramètres Wi-Fi système avec le réseau prérempli. Sur iOS, la connexion au réseau se fait directement.

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

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

connect

Se connecter à un réseau Wi-Fi. Sur Android, cela crée une connexion temporaire qui, par défaut, ne route pas le trafic via le réseau. Définissez autoRouteTraffic sur true pour lier le trafic de l'app au réseau connecté (utile pour les points d'accès locaux ou hébergés sur l'appareil). Pour une connexion persistante sur Android, utilisez plutôt addNetwork(). Sur iOS, cela crée une connexion persistante.

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

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

disconnect

Se déconnecter du réseau Wi-Fi actuel. Sur iOS, cela ne déconnecte que les réseaux ajoutés via ce plugin.

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

await CapacitorWifi.disconnect();

getAvailableNetworks

Récupère la liste des réseaux Wi-Fi disponibles lors du dernier scan. Disponible uniquement sur 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

Récupérer l'adresse IP actuelle de l'appareil. Disponible sur Android et iOS.

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

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

getRssi

Récupérer l'indicateur de force du signal reçu (RSSI) du réseau actuel en dBm. Disponible uniquement sur Android.

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

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

getSsid

Récupérer l'identifiant de service (SSID) du réseau actuel. Disponible sur Android et iOS.

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

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

getWifiInfo

Récupérer des informations complètes sur le réseau WiFi connecté. Cette méthode fournit des détails réseau incluant le SSID, le BSSID, l'adresse IP, la fréquence, la vitesse de liaison et la force du signal en un seul appel. Sur iOS, certains champs peuvent ne pas être disponibles et seront 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

Vérifiez si le Wi-Fi est activé sur l'appareil. Disponible uniquement sur Android.

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

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

startScan

Lancez le scan des réseaux Wi-Fi. Disponible uniquement sur Android. Les résultats sont transmis via l'écouteur d'événement ‘networksScanned’. Note : peut échouer en raison de la limitation du système ou de problèmes matériels.

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

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

checkPermissions

Vérifiez l'état actuel des permissions d'accès à la localisation.\nL'autorisation de localisation est requise pour les opérations Wi-Fi sur les deux plateformes.

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

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

requestPermissions

Demandez l'autorisation de localisation à l'utilisateur. L'autorisation de localisation est requise pour les opérations Wi-Fi sur les deux plateformes.

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

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

Référence de type

AddNetworkOptions

Options pour ajouter un réseau.

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

Options pour se connecter à un réseau.

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

Options pour se déconnecter d'un réseau.

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

GetAvailableNetworksResult

Résultat de getAvailableNetworks().

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

GetIpAddressResult

Résultat de getIpAddress().

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

GetRssiResult

Résultat de getRssi().

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

GetSsidResult

Résultat de getSsid().

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

WifiInfo

Informations WiFi complètes.

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

Résultat de isEnabled().

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

PermissionStatus

Statut de la permission.

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

RequestPermissionsOptions

Options pour demander les permissions.

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

NetworkSecurityType

Types de sécurité réseau.

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 de vérité

Cette page est générée à partir du src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Premiers pas pour planifier les opérations du dashboard et de API, connectez-l’à Utiliser @capgo/capacitor-wifi pour la capacité native dans la section Utiliser @capgo/capacitor-wifi, Aperçu de API pour les détails d'implémentation dans l'aperçu de API, Introduction pour les détails d'implémentation dans l'Introduction, Clés API pour les détails d'implémentation dans les clés API, et Appareils pour le détail d’implémentation dans Devices.