NWPathMonitor: o que é, monitoramento de rede e trabalho em iOS

O que é NWPathMonitor?

NWPathMonitor é uma classe do framework Network introduzida pela Apple no iOS 12 e macOS 10.14 Mojave. Ela fornece uma API moderna para rastrear mudanças no caminho de rede do dispositivo — a combinação de interfaces de rede através das quais o tráfego do aplicativo passa.

Antes do iOS 12, a biblioteca Reachability construída sobre o framework SystemConfiguration em C era usada para monitoramento de rede. NWPathMonitor é uma alternativa nativa em Swift com uma API mais rica, suporte para tipos de conexão modernos (VPN, multipath, LTE, 5G) e integração integrada com GCD.

A diferença chave entre NWPathMonitor e Reachability — o objeto NWPath fornece não apenas um status binário “disponível/indisponível”, mas uma imagem completa do caminho: interfaces usadas, sua prioridade, custos, status de roaming e capacidades de proxy e VPN. O desenvolvedor obtém informações abrangentes para tomar decisões sobre requisições de rede.

História do framework Network

O framework Network surgiu como uma substituição moderna para APIs de baixo nível em C — CFStream e BSD Sockets. Ele fornece uma interface unificada para comunicação de rede em todas as plataformas Apple, incluindo watchOS e tvOS. NWPathMonitor faz parte deste framework juntamente com NWConnection, NWListener e NWBrowser.

O framework Network é escrito em Swift e usa GCD para processamento assíncrono. Isso significa que os callbacks do NWPathMonitor executam na dispatch queue especificada, integrando-se à arquitetura de multithreading existente do aplicativo sem gerenciamento manual de threads.

Como usar NWPathMonitor em uma aplicação

O uso do NWPathMonitor começa com a criação de uma instância da classe e configuração do callback pathUpdateHandler. Em seguida, o método start é chamado com uma dispatch queue onde o closure será executado. O monitoramento é interrompido pelo método cancel, que também libera recursos.

import Network

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

    func startMonitoring() {
        monitor.pathUpdateHandler = { path in
            if path.status == .satisfied {
                print("Rede disponível")
            } else {
                print("Rede indisponível")
            }
        }
        monitor.start(on: queue)
    }

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

Trabalhando com tipo de interface

NWPathMonitor pode ser configurado para monitorar apenas um tipo de interface específico. Use o inicializador NWPathMonitor(requiredInterfaceType:) com o parâmetro NWInterface.InterfaceType — .wifi, .cellular, .wiredEthernet ou .loopback. Se nenhum tipo for especificado, o monitoramento cobre todas as interfaces.

Exemplo prático: um aplicativo de streaming pode monitorar apenas Wi-Fi e avisar o usuário sobre a mudança para dados móveis. Verificar isConstrained e isExpensive no NWPath permite determinar se a conexão atual é tarifada ou limitada em velocidade.

Ciclo de vida do monitoramento

O monitoramento deve iniciar ao lançar o aplicativo ou ao entrar em primeiro plano, e parar ao entrar em segundo plano. É recomendado criar uma instância de NWPathMonitor para todo o aplicativo (singleton) e usá-la de diferentes módulos através de um protocolo ou camada de serviço.

Propriedades e capacidades do NWPath

NWPath é um objeto passado para pathUpdateHandler que descreve o estado atual do caminho de rede. Ele contém cinco propriedades principais que cobrem a maioria dos cenários de monitoramento de rede. NWPath.Status — uma enumeração com três estados: satisfied (disponível), unsatisfied (indisponível) e requiresConnection (precisa de conexão).

Verificação de custos e restrições

A propriedade isExpensive é uma flag crítica para aplicativos que trabalham com grandes volumes de dados. Se isExpensive = true, o aplicativo deve reduzir a qualidade de streaming, adiar downloads de atualizações ou avisar o usuário. isConstrained indica que o Low Data Mode está ativado.

Para verificar a disponibilidade de internet (não apenas de rede), use o método usesInterfaceType. Se o dispositivo estiver conectado ao Wi-Fi sem internet — NWPath pode mostrar satisfied, mas o acesso real está ausente. Nesses casos, é necessária validação adicional via NWConnection.

Exemplos de implementação do NWPathMonitor

Vamos ver uma implementação avançada do NWPathMonitor com gerenciamento de custos, tipos de interface e notificação de ViewModel através de um publisher. O exemplo usa o framework Combine para atualizações reativas da UI quando o estado da rede muda.

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

Gerenciamento de perda de rede com ação adiada

Quando a conexão é perdida, pode ser necessário não apenas notificar a UI, mas também realizar ações adiadas — por exemplo, salvar um rascunho de requisição para envio posterior. Implemente uma fila de requisições adiadas que acumula operações durante o status unsatisfied e as envia quando satisfied é restaurado.

O padrão ReachabilityManager com delegado é ideal para esta tarefa: NWPathMonitor notifica o gerenciador, o gerenciador atualiza a fila e a UI. Quando o status muda para satisfied, a fila é automaticamente esvaziada e a UI recebe uma indicação de restauração da conexão.

NWPathMonitor vs Reachability

Antes do NWPathMonitor, a solução padrão para monitoramento de rede no iOS era a biblioteca Reachability da Apple (exemplo da documentação), construída sobre SystemConfiguration. As principais diferenças: Reachability funciona através de SCNetworkReachability em C, não suporta tipos de rede modernos e fornece apenas uma resposta binária de disponibilidade.

NWPathMonitor resolve essas limitações: é escrito em Swift, suporta VPN, multipath, 5G e LTE, fornece informações detalhadas sobre cada interface e funciona assincronamente através do GCD. Reachability ainda é usado em projetos com suporte mínimo ao iOS 11 e inferior.

Quando usar Reachability

Se seu aplicativo suporta iOS 11 e inferior, Reachability continua sendo a única opção. Para projetos iOS 12+, é recomendado usar NWPathMonitor diretamente — ele se integra melhor com código Swift moderno, Combine e SwiftUI.

A migração de Reachability para NWPathMonitor é simples: basta substituir as chamadas SCNetworkReachability por NWPathMonitor, mantendo a mesma lógica de tratamento. Uma camada de abstração (NetworkMonitorProtocol) permitirá alternar entre implementações sem alterar a lógica de negócios do aplicativo.