Connectivity Manager: cos’è, metodi e monitoraggio della connessione

Cos’è Connectivity Manager?

ConnectivityManager è un servizio di sistema del sistema operativo Android, accessibile tramite Context.getSystemService(Context.CONNECTIVITY_SERVICE). Fornisce un’API per ottenere informazioni sulla connessione di rete del dispositivo, monitorare i cambiamenti di rete e gestire le richieste di rete dell’applicazione. Connectivity Manager fa parte di Android Framework dalla prima versione della piattaforma (API Level 1) e ha subito cambiamenti significativi nel corso dei decenni: dal semplice getActiveNetworkInfo() al moderno modello reattivo con NetworkCallback e NetworkRequest.

Le principali capacità di Connectivity Manager includono: verificare la presenza di una connessione di rete attiva, determinare il tipo di rete (Wi-Fi, dati mobili, Ethernet, Bluetooth, VPN), monitorare i cambiamenti di stato della rete in tempo reale, ottenere informazioni sulla larghezza di banda e sulla latenza, e gestire le richieste di rete dell’applicazione. ConnectivityManager viene utilizzato insieme a WorkManager e Repository per implementare un’architettura Offline-First, il caricamento adattivo dei contenuti e l’ottimizzazione dell’applicazione in base alla qualità della connessione.

A partire da Android 10 (API 29), Google ha cambiato l’approccio al lavoro con ConnectivityManager. Il metodo getActiveNetworkInfo() è dichiarato deprecato e al suo posto si raccomanda di utilizzare registerDefaultNetworkCallback() o registerNetworkCallback() con NetworkRequest. La nuova API fornisce informazioni di rete più dettagliate, inclusa la possibilità di rilevare portali captive (Wi-Fi con autenticazione) e valutare la qualità della connessione. ConnectivityManager è anche integrato con la famiglia Jetpack: la libreria ConnectivityManager è stata rilasciata nel 2024 come parte di Jetpack per semplificare il monitoraggio di rete nelle applicazioni Compose.

Il ruolo di Connectivity Manager nell’architettura dell’applicazione

Nell’architettura moderna di Android, Connectivity Manager viene utilizzato a livello di repository o UseCase per prendere decisioni sulle richieste di rete. Il livello Repository verifica lo stato della rete prima di chiamare l’API: se la rete non è disponibile, i dati vengono restituiti dall’archivio locale (Room). Se la rete è disponibile, viene effettuata una richiesta al server e il risultato viene salvato in Room. Il ViewModel si iscrive a un Flow da Room e non conosce i dettagli dell’interazione di rete — ciò consente di testare ogni livello in modo indipendente.

Come funziona Connectivity Manager

Connectivity Manager ottiene le informazioni sullo stato della rete dal servizio di sistema connectivity, che interagisce con le interfacce di rete del kernel Linux. Quando il dispositivo si connette al Wi-Fi o attiva i dati mobili, il kernel notifica il servizio di sistema, che aggiorna il suo stato interno e notifica tutti i callback registrati. L’architettura di ConnectivityManager si basa sul pattern Observer: l’applicazione registra un NetworkCallback e riceve notifiche su qualsiasi cambiamento di rete — stabilimento della connessione, perdita di connessione, cambio di tipo di rete o degrado della qualità.

L’API moderna di ConnectivityManager utilizza NetworkRequest per filtrare gli eventi di rete. NetworkRequest consente di specificare requisiti per la rete: trasporto (Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET), capacità Internet (NetworkCapabilities.NET_CAPABILITY_INTERNET) e altri criteri. Se un’applicazione necessita solo di Wi-Fi per scaricare file di grandi dimensioni, crea un NetworkRequest con Transport.WIFI e registra un callback. Il sistema notificherà l’applicazione solo quando la connessione Wi-Fi cambia, ignorando gli eventi della rete mobile.

Una caratteristica importante di Connectivity Manager su Android 12+ è la rete basata sulle capacità. L’applicazione non verifica semplicemente “c’è Internet?”, ma può valutare quale tipo di traffico è disponibile. Ad esempio, NET_CAPABILITY_NOT_METERED indica una connessione illimitata (Wi-Fi), NET_CAPABILITY_NOT_ROAMING indica che il dispositivo non è in roaming. Ciò consente di prendere decisioni: scaricare video solo in Wi-Fi, posticipare la sincronizzazione in roaming, o utilizzare i dati mobili solo per richieste critiche.

Permessi per Connectivity Manager

Per utilizzare Connectivity Manager in un’applicazione Android sono necessari permessi. ACCESS_NETWORK_STATE è un permesso obbligatorio per leggere le informazioni di rete, dichiarato in AndroidManifest.xml. Senza questo permesso, ConnectivityManager restituirà null per getActiveNetwork() e non invocherà i callback. Per eseguire operazioni di rete, è necessario anche il permesso INTERNET. A partire da Android 10 (API 29), l’applicazione può verificare lo stato della rete senza permessi aggiuntivi in fase di esecuzione — ACCESS_NETWORK_STATE è un permesso normale e viene concesso automaticamente durante l’installazione.

Metodi principali di Connectivity Manager

Il moderno Connectivity Manager fornisce diversi metodi chiave per lavorare con la rete. getActiveNetwork() (API 23+) restituisce l’oggetto Network della rete attiva corrente o null se il dispositivo non è connesso. Questo metodo non richiede callback ed è adatto per verifiche occasionali. L’oggetto Network può essere passato a NetworkCapabilities per ottenere informazioni dettagliate: tipo di trasporto, stato di tariffazione, roaming, capacità Internet e altre caratteristiche.

registerDefaultNetworkCallback() (API 24+) è il metodo preferito per monitorare la rete. L’applicazione registra un callback che viene invocato per qualsiasi cambiamento nella rete predefinita (la rete attraverso cui l’applicazione invia il traffico). Il callback riceve un oggetto Network che può essere utilizzato per associare socket e client HTTP. Questo metodo sostituisce il deprecato getActiveNetworkInfo() e fornisce un monitoraggio reattivo della rete senza polling.

registerNetworkCallback() (API 21+) consente di iscriversi ai cambiamenti di un tipo di rete specifico tramite NetworkRequest. Ad esempio, un’applicazione può tracciare solo le reti Wi-Fi utilizzando new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build(). Il sistema notificherà l’applicazione sulla connessione/disconnessione Wi-Fi senza influenzare gli eventi della rete mobile. NetworkCapabilities.getLinkDownstreamBandwidthKbps() restituisce una stima della larghezza di banda in downstream in kbit/s, consentendo di adattare la qualità del contenuto alla velocità della connessione.

ConnectivityManager in Jetpack Compose

La libreria Jetpack Connectivity (androidx.core:core-ktx) fornisce estensioni convenienti per lavorare con ConnectivityManager in Compose. La funzione ConnectivityManager.observeAsState() restituisce un State che viene aggiornato quando la rete cambia. Il componente @Composable NetworkStatus() visualizza lo stato della connessione e si ridisegna automaticamente ai cambiamenti. Ciò solleva lo sviluppatore dalla gestione manuale dei callback e del ciclo di vita di Activity/Fragment.

NetworkCallback e gestione dei cambiamenti di rete

ConnectivityManager.NetworkCallback è una classe astratta con metodi che vengono chiamati dal sistema quando lo stato della rete cambia. onAvailable(Network) viene chiamato quando una rete diventa disponibile. L’applicazione riceve un oggetto Network che può essere utilizzato per associare socket tramite Network.bindSocket(). onLost(Network) viene chiamato quando una rete diventa indisponibile. L’applicazione dovrebbe passare ai dati locali o mostrare un messaggio di assenza di connessione. onCapabilitiesChanged(Network, NetworkCapabilities) viene chiamato quando le caratteristiche della rete cambiano (ad esempio, passando dal Wi-Fi ai dati mobili).

La corretta gestione dei cambiamenti di rete richiede la considerazione del ciclo di vita del componente. Il callback deve essere registrato in onStart()/onResume() e annullato in onStop()/onPause(). Se il callback non viene annullato, può continuare a essere eseguito dopo la distruzione dell’Activity, causando perdite di memoria e potenziali NullPointerException quando il callback tenta di aggiornare l’interfaccia di un componente distrutto. Utilizza lifecycleScope o repeatOnLifecycle per la gestione automatica della registrazione. In Jetpack Compose, utilizza DisposableEffect per registrare e annullare il callback.

Gestione dei portali captive è una caratteristica importante di ConnectivityManager a partire da Android 10. CAPTIVE_PORTAL è uno scenario in cui una rete Wi-Fi è disponibile ma richiede l’autenticazione tramite una pagina web (aeroporti, hotel, bar). NetworkCapabilities.NET_CAPABILITY_VALIDATED indica che la rete ha accesso completo a Internet. Se NET_CAPABILITY_VALIDATED è assente, l’applicazione può aprire un browser per l’autenticazione del portale captive. Il metodo isCaptivePortal(), aggiunto in Android 11 (API 30), viene utilizzato per rilevare i portali captive.

Rete per scopi specifici (NetworkRequest)

ConnectivityManager consente di richiedere una rete per scopi specifici tramite requestNetwork() e bindProcessToNetwork(). Ad esempio, un’applicazione per il download di file di grandi dimensioni può richiedere una rete Wi-Fi anche se i dati mobili sono attivi. Per farlo, viene creato un NetworkRequest con addTransportType(TRANSPORT_WIFI) e, quando il Wi-Fi è disponibile, il sistema chiama onAvailable(). L’applicazione associa i socket a questa rete tramite network.bindSocket() o OkHttp con un oggetto Network configurato. Ciò offre un controllo flessibile sull’utilizzo delle interfacce di rete.

Esempio di implementazione in Kotlin

Esaminiamo un esempio completo di utilizzo di ConnectivityManager con l’API moderna (NetworkCallback) in Clean Architecture. NetworkMonitor è una classe wrapper attorno a ConnectivityManager che fornisce lo stato della rete in modo reattivo tramite StateFlow. Il ViewModel si iscrive a questo Flow e passa lo stato all’interfaccia utente. Il Repository utilizza NetworkMonitor per prendere decisioni sulle richieste di rete. Questo approccio garantisce testabilità e isolamento delle dipendenze della piattaforma.

L’esempio seguente mostra come utilizzare correttamente ConnectivityManager con registerDefaultNetworkCallback. La classe NetworkMonitor incapsula il lavoro con il servizio di sistema e fornisce un Kotlin Flow pulito. Registra il callback all’avvio e lo annulla al termine del ciclo di vita. Il funzionamento asincrono è garantito tramite coroutine e callbackFlow — un ponte tra lo stile a callback di ConnectivityManager e lo stile reattivo Flow di Kotlin.

class NetworkMonitor(
    private val connectivityManager: ConnectivityManager
) {
    val isOnline: StateFlow<Boolean> = callbackFlow {
        val callback = object : ConnectivityManager.NetworkCallback() {
            override fun onAvailable(network: Network) {
                trySend(true)
            }
            override fun onLost(network: Network) {
                trySend(false)
            }
            override fun onCapabilitiesChanged(
                network: Network,
                caps: NetworkCapabilities
            ) {
                val connected = caps.hasCapability(
                    NetworkCapabilities.NET_CAPABILITY_INTERNET
                )
                trySend(connected)
            }
        }
        connectivityManager.registerDefaultNetworkCallback(callback)
        awaitClose {
            connectivityManager.unregisterNetworkCallback(callback)
        }
    }.stateIn(
        CoroutineScope(Dispatchers.Default),
        SharingStarted.WhileSubscribed(5000),
        initialValue = checkInitialState()
    )

    private fun checkInitialState(): Boolean {
        val network = connectivityManager.getActiveNetwork() ?: return false
        val caps = connectivityManager.getNetworkCapabilities(network) ?: return false
        return caps.hasCapability(
            NetworkCapabilities.NET_CAPABILITY_INTERNET
        )
    }
}

Utilizzo di NetworkMonitor in ViewModel e Repository

Il ViewModel si iscrive a NetworkMonitor.isOnline tramite stateIn() e passa lo stato a Compose. Il Repository verifica il valore corrente di isOnline.value prima di chiamare l’API: se false — restituisce un Flow da Room. Se true — chiama l’API, salva il risultato in Room e restituisce un Flow da Room. WorkManager utilizza NetworkType.CONNECTED per limitare le attività in background. Il test di NetworkMonitor viene eseguito con un oggetto mock di ConnectivityManager e un NetworkCallback fittizio, consentendo di emulare qualsiasi scenario di rete nei test unitari.

Best practice ed errori comuni

La prima regola quando si lavora con ConnectivityManager è di non utilizzare l’API deprecata. getActiveNetworkInfo() è deprecato da API 29 e può restituire dati errati sulle nuove versioni di Android. Utilizza invece getActiveNetwork() + getNetworkCapabilities() per verifiche occasionali e registerDefaultNetworkCallback() per il monitoraggio continuo. Il vecchio metodo inoltre non distingue tra reti con portale captive e Internet completo, portando a falsi positivi.

La seconda regola è annullare sempre la registrazione del callback. Se un’Activity registra un NetworkCallback in onStart() ma non lo annulla in onStop(), il callback continua a essere eseguito dopo la distruzione dell’Activity. Ciò causa perdite di memoria e potenziali NullPointerException quando il callback tenta di aggiornare l’interfaccia di un componente distrutto. Utilizza lifecycleScope o repeatOnLifecycle per la gestione automatica della registrazione. In Jetpack Compose, utilizza DisposableEffect per registrare e annullare il callback.

Il terzo errore comune è verificare solo la disponibilità della rete senza considerare la sua qualità. Un semplice “c’è Internet?” non è sufficiente per prendere decisioni. L’applicazione dovrebbe verificare NET_CAPABILITY_NOT_METERED per il download di file di grandi dimensioni, NET_CAPABILITY_NOT_ROAMING per la sincronizzazione in background e NET_CAPABILITY_VALIDATED per confermare l’accesso a Internet. Ignorare questi flag porta l’applicazione a tentare di scaricare video in roaming o di sincronizzare dati attraverso un portale captive di un hotel.

La quarta regola è di non utilizzare ConnectivityManager per verificare la disponibilità di un server specifico. ConnectivityManager segnala lo stato della rete sul dispositivo, ma non garantisce che il server sia raggiungibile. Per verificare la disponibilità di un’API, utilizza una richiesta HTTP con timeout breve o un Health Check. ConnectivityManager + ping HTTP è una combinazione affidabile: prima verifica la presenza della rete, poi effettua una richiesta leggera al server per confermare la raggiungibilità effettiva.

Test di ConnectivityManager

Per i test unitari, utilizza Robolectric con ShadowConnectivityManager, che consente di emulare gli stati di rete. Per i test di integrazione — Android Test Orchestrator con commutazione della Modalità aereo. Nei test, verifica scenari: transizione da online a offline, comparsa del Wi-Fi con dati mobili attivi, perdita di rete durante una richiesta, portale captive, roaming. Per il mocking nei test unitari, utilizza un’interfaccia wrapper (ad esempio, NetworkMonitorInterface) che può essere sostituita con un oggetto mock senza dipendenze dalla piattaforma.