NetworkCallback: cos'è, applicazione e gestione della rete in Android

Cos'è NetworkCallback?

NetworkCallback è una classe astratta del pacchetto android.net, che fa parte dell'Android SDK. È progettata per ricevere notifiche sui cambiamenti dello stato della connessione di rete tramite il servizio di sistema ConnectivityManager.

Prima di NetworkCallback, gli sviluppatori utilizzavano BroadcastReceiver per tracciare i cambiamenti di rete. Questo approccio richiedeva una registrazione costante nel manifesto, funzionava con ritardi e non forniva informazioni dettagliate sulle caratteristiche della connessione. Android 5.0 (API 21) ha introdotto NetworkCallback come alternativa più flessibile e performante.

Il callback funziona in modo asincrono: l'app si iscrive agli eventi tramite ConnectivityManager e il sistema chiama i metodi del callback quando lo stato della rete cambia. Questo elimina la necessità di polling periodico dello stato della rete, risparmiando risorse di batteria e CPU.

Come funziona il callback in Android

ConnectivityManager gestisce tutte le interfacce di rete del dispositivo — Wi-Fi, dati mobili, Ethernet, VPN. Quando una di queste interfacce cambia, il sistema crea un oggetto Network e lo passa al metodo corrispondente del callback registrato. Ogni Network ha un identificatore univoco che cambia alla riconnessione.

Il callback non è legato a un tipo di rete specifico — può tracciare tutte le interfacce disponibili contemporaneamente. Per filtrare i tipi di connessione, si usa la classe NetworkRequest, che specifica i protocolli di trasporto richiesti (Wi-Fi, dati cellulari, Ethernet) e le capacità della rete.

Come Registrare NetworkCallback nella Tua App

La registrazione di NetworkCallback avviene tramite il metodo ConnectivityManager.registerNetworkCallback. Il primo parametro è un NetworkRequest.Builder che descrive i requisiti di rete, il secondo è un'istanza del callback. Il permesso ACCESS_NETWORK_STATE è richiesto nel manifesto.

class NetworkMonitor(private val context: Context) {

    private val connectivityManager =
        context.getSystemService(Context.CONNECTIVITY_SERVICE)
            as ConnectivityManager

    private val callback =
        object : ConnectivityManager.NetworkCallback() {

        override fun onAvailable(network: Network) {
            Log.d("Network", "Available: ${network}")
        }

        override fun onLost(network: Network) {
            Log.d("Network", "Lost: ${network}")
        }
    }

    fun register() {
        connectivityManager.registerNetworkCallback(
            NetworkRequest.Builder().build(), callback
        )
    }

    fun unregister() {
        connectivityManager.unregisterNetworkCallback(callback)
    }
}

Registrazione in Activity e Fragment

Si consiglia di registrare NetworkCallback quando l'app è in primo piano e di annullarlo quando passa in secondo piano. In Activity, usa onStart e onStop per gestire il ciclo di vita del callback. In Fragment, usa onResume e onPause.

Per semplificare la gestione della registrazione, puoi utilizzare componenti Lifecycle-aware. La libreria AndroidX Lifecycle consente di creare un LifecycleObserver personalizzato che registra e annulla automaticamente il callback quando lo stato del ciclo di vita cambia.

Registrazione in un Service

Per le attività in background, la registrazione avviene in un Service o WorkManager. Nota che su Android 8+, i servizi in background hanno restrizioni di avvio. WorkManager con NetworkType è un modo più affidabile per eseguire attività sotto uno stato di rete specifico, poiché è integrato con l'API di compatibilità e rispetta la modalità Doze.

Metodi Principali di NetworkCallback

NetworkCallback fornisce un insieme di metodi che vengono chiamati quando lo stato della rete cambia. Non tutti i metodi devono essere sovrascritti — implementa solo quelli necessari per il compito specifico della tua app. onAvailable e onLost sono il minimo richiesto per il monitoraggio di base della connessione.

Metodo onCapabilitiesChanged

Questo metodo è fondamentale per ottenere informazioni dettagliate sulla rete. Il parametro NetworkCapabilities contiene flag: NET_CAPABILITY_INTERNET — accesso a internet disponibile, NET_CAPABILITY_NOT_METERED — connessione illimitata, NET_CAPABILITY_NOT_ROAMING — nessun roaming. Si possono anche conoscere la latenza del segnale e la larghezza di banda.

I portali captivi sono un caso speciale: quando ci si connette a una rete Wi-Fi pubblica tramite un portale, il metodo onCapabilitiesChanged non mostra immediatamente INTERNET. La rete è inizialmente disponibile ma senza internet — è necessaria l'autorizzazione tramite browser. Gli sviluppatori devono considerare questo ritardo nella logica dell'app.

Metodo onBlockedStatusChanged

Viene chiamato quando il sistema blocca il traffico di rete per l'app — ad esempio, quando la modalità di risparmio dati è attivata o i dati in background sono limitati. onBlockedStatusChanged consente all'app di sapere che le sue richieste di rete sono temporaneamente vietate e di passare all'elaborazione locale.

Esempi di Implementazione di NetworkCallback

Vediamo un'implementazione pratica di NetworkCallback per monitorare l'accesso a internet e gestire i portali captivi. L'esempio seguente mostra la verifica di NET_CAPABILITY_INTERNET e la validazione della connessione tramite una richiesta HTTP al server di Google.

val networkCallback = object : ConnectivityManager.NetworkCallback() {

    override fun onCapabilitiesChanged(
        network: Network,
        caps: NetworkCapabilities
    ) {
        val hasInternet = caps.hasCapability(
            NetworkCapabilities.NET_CAPABILITY_INTERNET
        )
        val isMetered = caps.hasCapability(
            NetworkCapabilities.NET_CAPABILITY_NOT_METERED
        ).not()

        when {
            hasInternet && isMetered ->
                Log.d("Network", "Mobile data connected")
            hasInternet ->
                Log.d("Network", "Wi-Fi connected")
            else ->
                Log.d("Network", "No internet access")
        }
    }

    override fun onLost(network: Network) {
        Log.d("Network", "Connection lost: ${network}")
        // Interrompere richieste di rete
    }
}

Gestione dei Portali Captivi

Quando ci si connette a una rete pubblica con autorizzazione (bar, aeroporto), il sistema prima segnala onAvailable, ma onCapabilitiesChanged potrebbe non mostrare INTERNET. In tali casi, è necessaria una verifica aggiuntiva tramite una richiesta HTTP a un endpoint stabile, come https://www.google.com/generate_204.

Se la richiesta restituisce il codice 204 — internet è disponibile. Se c'è un reindirizzamento (301, 302, 307) — è necessaria l'autorizzazione tramite browser. In questo caso, puoi aprire una WebView o un Intent con l'URL di reindirizzamento per completare l'autenticazione sul portale.

fun Context.validateInternet(network: Network) {
    CoroutineScope(Dispatchers.IO).launch {
        try {
            val url = URL("https://www.google.com/generate_204")
            val connection =
                network.openConnection(url) as HttpURLConnection
            connection.instanceFollowRedirects = false
            connection.connect()
            when (connection.responseCode) {
                HttpURLConnection.HTTP_NO_CONTENT ->
                    Log.d("Network", "Internet is available")
                in HttpURLConnection.HTTP_MOVED_PERM
                        ..HttpURLConnection.HTTP_TEMP_REDIRECT ->
                    Log.d("Network", "Captive portal detected")
            }
            connection.disconnect()
        } catch (e: Exception) {
            Log.e("Network", "Validation failed: ${e.message}")
        }
    }
}

Differenze da Altri Metodi di Monitoraggio della Rete

Prima di NetworkCallback, il metodo principale per monitorare la rete era BroadcastReceiver con il filtro android.net.conn.CONNECTIVITY_CHANGE. Questo approccio presentava notevoli svantaggi: ritardi di diversi secondi, mancanza di informazioni sul tipo di interfaccia e aumento del consumo energetico a causa del risveglio costante del dispositivo.

Un'alternativa moderna è LiveData o StateFlow combinati con NetworkCallback. Il pattern consiste nell'incapsulare il callback in un flusso reattivo che notifica automaticamente all'UI i cambiamenti di stato. Ad esempio, un MutableStateFlow con tipo NetworkStatus viene aggiornato all'interno dei metodi del callback e un ViewCollector si iscrive ai cambiamenti.

Lavoro in Modalità Background

A partire da Android 10, le restrizioni in background sono più severe e NetworkCallback potrebbe non essere chiamato quando l'app è in background. Per attività critiche — come caricare dati quando la rete diventa disponibile — usa WorkManager con il vincolo NetworkType.CONNECTED. WorkManager garantisce l'esecuzione dell'attività quando le condizioni di rete sono soddisfatte.

In Android 12+, c'è una restrizione sulla registrazione nel manifesto di BroadcastReceiver per CONNECTIVITY_ACTION. Gli sviluppatori devono migrare a NetworkCallback o usare WorkManager. La politica di Google Play da agosto 2022 richiede la rimozione della registrazione nel manifesto per questa azione.