NWPathMonitor: cos’è, monitoraggio della rete e lavoro in iOS

Cos’è NWPathMonitor?

NWPathMonitor è una classe del framework Network introdotta da Apple in iOS 12 e macOS 10.14 Mojave. Fornisce una API moderna per tracciare i cambiamenti nel percorso di rete del dispositivo — la combinazione di interfacce di rete attraverso cui passa il traffico dell’applicazione.

Prima di iOS 12, la libreria Reachability costruita sul framework SystemConfiguration in C veniva utilizzata per il monitoraggio della rete. NWPathMonitor è un’alternativa nativa in Swift con una API più ricca, supporto per tipi di connessione moderni (VPN, multipath, LTE, 5G) e integrazione integrata con GCD.

La differenza chiave tra NWPathMonitor e Reachability — l’oggetto NWPath fornisce non solo uno stato binario “disponibile/non disponibile”, ma un quadro completo del percorso: interfacce utilizzate, loro priorità, costi, stato di roaming e capacità di proxy e VPN. Lo sviluppatore ottiene informazioni esaustive per prendere decisioni sulle richieste di rete.

Storia del framework Network

Il framework Network è emerso come sostituto moderno delle API C di basso livello — CFStream e BSD Sockets. Fornisce un’interfaccia unificata per la comunicazione di rete su tutte le piattaforme Apple, inclusi watchOS e tvOS. NWPathMonitor fa parte di questo framework insieme a NWConnection, NWListener e NWBrowser.

Il framework Network è scritto in Swift e utilizza GCD per l’elaborazione asincrona. Ciò significa che i callback di NWPathMonitor vengono eseguiti sulla dispatch queue specificata, integrandosi con l’architettura di multithreading esistente dell’applicazione senza gestione manuale dei thread.

Come usare NWPathMonitor in un’applicazione

L’uso di NWPathMonitor inizia con la creazione di un’istanza della classe e la configurazione del callback pathUpdateHandler. Quindi il metodo start viene chiamato con una dispatch queue dove verrà eseguita la closure. Il monitoraggio viene arrestato dal metodo cancel, che rilascia anche le risorse.

import Network

class NetworkMonitor {
    private let monitor = NWPathMonitor()
    private let queue = DispatchQueue("monitor")

    func startMonitoring() {
        monitor.pathUpdateHandler = { path in
            if path.status == .satisfied {
                print("Rete disponibile")
            } else {
                print("Rete non disponibile")
            }
        }
        monitor.start(on: queue)
    }

    func stopMonitoring() {
        monitor.cancel()
    }
}

Lavorare con il tipo di interfaccia

NWPathMonitor può essere configurato per monitorare solo un tipo di interfaccia specifico. Utilizzare l’inizializzatore NWPathMonitor(requiredInterfaceType:) con il parametro NWInterface.InterfaceType — .wifi, .cellular, .wiredEthernet o .loopback. Se nessun tipo è specificato, il monitoraggio copre tutte le interfacce.

Esempio pratico: un’applicazione di streaming può monitorare solo il Wi-Fi e avvisare l’utente del passaggio ai dati cellulari. Verificare isConstrained e isExpensive in NWPath consente di determinare se la connessione corrente è a pagamento o limitata in velocità.

Ciclo di vita del monitoraggio

Il monitoraggio dovrebbe iniziare all’avvio dell’applicazione o quando si passa in primo piano e fermarsi quando si passa in secondo piano. Si raccomanda di creare una singola istanza di NWPathMonitor per l’intera applicazione (singleton) e utilizzarla da diversi moduli tramite un protocollo o un livello di servizio.

Proprietà e capacità di NWPath

NWPath è un oggetto passato a pathUpdateHandler che descrive lo stato corrente del percorso di rete. Contiene cinque proprietà chiave che coprono la maggior parte degli scenari di monitoraggio della rete. NWPath.Status — un’enumerazione con tre stati: satisfied (disponibile), unsatisfied (non disponibile) e requiresConnection (richiede connessione).

Verifica di costi e restrizioni

La proprietà isExpensive è un flag critico per le applicazioni che lavorano con grandi volumi di dati. Se isExpensive = true, l’applicazione dovrebbe ridurre la qualità dello streaming, posticipare i download degli aggiornamenti o avvisare l’utente. isConstrained indica che la Low Data Mode è attiva.

Per verificare la disponibilità di Internet (non solo della rete), utilizzare il metodo usesInterfaceType. Se il dispositivo è connesso al Wi-Fi senza Internet — NWPath potrebbe mostrare satisfied, ma l’accesso effettivo è assente. In questi casi, è necessaria una validazione aggiuntiva tramite NWConnection.

Esempi di implementazione di NWPathMonitor

Vediamo un’implementazione avanzata di NWPathMonitor con gestione dei costi, tipi di interfaccia e notifica al ViewModel tramite un publisher. L’esempio utilizza il framework Combine per aggiornamenti reattivi dell’interfaccia utente quando lo stato della rete cambia.

import Network
import Combine

final class NetworkManager: ObservableObject {
    static let shared = NetworkManager()
    @Published private(set) var isConnected = true
    @Published private(set) var isExpensive = false

    private let monitor = NWPathMonitor()
    private let queue = DispatchQueue("NetworkMonitor")

    private init() {
        monitor.pathUpdateHandler = { [weak self] path in
            DispatchQueue.main.async {
                self?.isConnected = path.status == .satisfied
                self?.isExpensive = path.isExpensive
            }
        }
        monitor.start(on: queue)
    }

    func checkInterface() -> NWInterface.InterfaceType {
        let path = monitor.currentPath
        if path.usesInterfaceType(.wifi) { return .wifi }
        if path.usesInterfaceType(.cellular) { return .cellular }
        return .other
    }
}

Gestione della perdita di rete con azione differita

Quando la connessione viene persa, potrebbe essere necessario non solo notificare l’interfaccia utente ma anche eseguire azioni differite — ad esempio, salvare una bozza di richiesta per l’invio successivo. Implementare una coda di richieste differite che accumula operazioni durante lo stato unsatisfied e le invia quando satisfied viene ripristinato.

Il pattern ReachabilityManager con delegato è ideale per questo compito: NWPathMonitor notifica il manager, il manager aggiorna la coda e l’interfaccia utente. Quando lo stato passa a satisfied, la coda viene automaticamente svuotata e l’interfaccia utente riceve un’indicazione di ripristino della connessione.

NWPathMonitor vs Reachability

Prima di NWPathMonitor, la soluzione standard per il monitoraggio della rete in iOS era la libreria Reachability di Apple (esempio dalla documentazione), costruita su SystemConfiguration. Le principali differenze: Reachability funziona tramite SCNetworkReachability in C, non supporta i tipi di rete moderni e fornisce solo una risposta binaria di disponibilità.

NWPathMonitor risolve queste limitazioni: è scritto in Swift, supporta VPN, multipath, 5G e LTE, fornisce informazioni dettagliate su ciascuna interfaccia e funziona in modo asincrono tramite GCD. Reachability è ancora utilizzato in progetti con supporto minimo a iOS 11 e inferiore.

Quando usare Reachability

Se la tua applicazione supporta iOS 11 e inferiore, Reachability rimane l’unica opzione. Per i progetti iOS 12+, si raccomanda di utilizzare direttamente NWPathMonitor — si integra meglio con il codice Swift moderno, Combine e SwiftUI.

La migrazione da Reachability a NWPathMonitor è semplice: basta sostituire le chiamate SCNetworkReachability con NWPathMonitor, mantenendo la stessa logica di gestione. Un livello di astrazione (NetworkMonitorProtocol) consentirà di passare da un’implementazione all’altra senza modificare la logica di business dell’applicazione.