Connectivity Manager: ce este, metode și monitorizarea conexiunii

Ce este Connectivity Manager?

ConnectivityManager — este serviciul de sistem al sistemului de operare Android, accesibil prin Context.getSystemService(Context.CONNECTIVITY_SERVICE). Oferă API pentru obținerea informațiilor despre conexiunea de rețea a dispozitivului, monitorizarea schimbărilor rețelei și gestionarea solicitărilor de rețea ale aplicației. Connectivity Manager face parte din Android Framework de la prima versiune a platformei (API Level 1) și de-a lungul deceniilor a suferit modificări semnificative: de la simplul getActiveNetworkInfo() la modelul reactiv modern cu NetworkCallback și NetworkRequest.

Capabilitățile principale ale Connectivity Manager includ: verificarea existenței unei conexiuni de rețea active, determinarea tipului de rețea (Wi-Fi, date mobile, Ethernet, Bluetooth, VPN), monitorizarea modificărilor stării rețelei în timp real, obținerea de informații despre lățimea de bandă și întârzieri, gestionarea solicitărilor de rețea ale aplicației. ConnectivityManager este utilizat împreună cu WorkManager și Repository pentru implementarea arhitecturii Offline-First, încărcarea adaptivă a conținutului și optimizarea funcționării aplicației în funcție de calitatea conexiunii.

Începând cu Android 10 (API 29), Google a schimbat abordarea de lucru cu ConnectivityManager. Metoda getActiveNetworkInfo() a fost declarată deprecated, iar în locul ei se recomandă utilizarea registerDefaultNetworkCallback() sau registerNetworkCallback() cu NetworkRequest. Noul API oferă informații mai detaliate despre rețea, inclusiv posibilitatea detectării portalurilor captive (Wi-Fi cu autentificare) și evaluarea calității conexiunii. ConnectivityManager este, de asemenea, integrat cu familia Jetpack: biblioteca ConnectivityManager a fost lansată în 2024 ca parte a Jetpack pentru simplificarea monitorizării rețelei în aplicațiile Compose.

Rolul Connectivity Manager în arhitectura aplicației

În arhitectura modernă Android, Connectivity Manager este utilizat la nivel de repository sau UseCase pentru luarea deciziilor privind solicitările de rețea. Stratul Repository verifică starea rețelei înainte de apelarea API: dacă rețeaua este indisponibilă, se returnează date din stocarea locală (Room). Dacă rețeaua este disponibilă, se execută o solicitare către server, iar rezultatul este salvat în Room. ViewModel se abonează la Flow din Room și nu cunoaște detaliile interacțiunii de rețea — acest lucru permite testarea ușoară a fiecărui strat independent.

Cum funcționează Connectivity Manager

Connectivity Manager primește informații despre starea rețelei de la serviciul de sistem connectivity, care interacționează cu interfețele de rețea ale nucleului Linux. Când dispozitivul se conectează la Wi-Fi sau activează datele mobile, nucleul notifică serviciul de sistem, care actualizează starea internă și notifică toate callback-urile înregistrate. Arhitectura ConnectivityManager este construită pe modelul Observer: aplicația înregistrează NetworkCallback și primește notificări despre orice modificări ale rețelei — apariția conexiunii, pierderea acesteia, schimbarea tipului de rețea sau deteriorarea calității.

API-ul modern ConnectivityManager utilizează NetworkRequest pentru filtrarea evenimentelor de rețea. NetworkRequest permite specificarea cerințelor pentru rețea: transport (Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET), capacitatea de a accesa internetul (NetworkCapabilities.NET_CAPABILITY_INTERNET) și alte criterii. Dacă aplicația are nevoie doar de Wi-Fi pentru descărcarea fișierelor mari, creează un NetworkRequest cu Transport.WIFI și înregistrează un callback. Sistemul va notifica aplicația doar la modificarea conexiunii Wi-Fi, ignorând evenimentele rețelei mobile.

O caracteristică importantă a Connectivity Manager pe Android 12+ este rețeaua bazată pe capacități (capabilities-based networking). Aplicația nu verifică doar „există internet", ci poate evalua ce tip de trafic este disponibil. De exemplu, NET_CAPABILITY_NOT_METERED indică o conexiune nelimitată (Wi-Fi), NET_CAPABILITY_NOT_ROAMING — că dispozitivul nu este în roaming. Acest lucru permite luarea deciziilor: încărcarea videoclipurilor doar prin Wi-Fi, amânarea sincronizării în roaming sau utilizarea datelor mobile doar pentru solicitări critice.

Permisiuni pentru Connectivity Manager

Pentru utilizarea Connectivity Manager într-o aplicație Android sunt necesare permisiuni. ACCESS_NETWORK_STATE — permisiunea obligatorie pentru citirea informațiilor despre rețea, declarată în AndroidManifest.xml. Fără această permisiune, ConnectivityManager va returna null pentru getActiveNetwork() și nu va apela callback-urile. Pentru executarea operațiunilor de rețea este necesară și permisiunea INTERNET. Începând cu Android 10 (API 29), aplicația poate verifica starea rețelei fără permisiuni suplimentare runtime — ACCESS_NETWORK_STATE este o permisiune normală (normal permission) și este acordată automat la instalare.

Metodele principale ale Connectivity Manager

Connectivity Manager modern oferă câteva metode cheie pentru lucrul cu rețeaua. getActiveNetwork() (API 23+) returnează obiectul Network al rețelei active curente sau null dacă dispozitivul nu este conectat. Această metodă nu necesită callback-uri și este potrivită pentru verificarea unică. Obiectul Network poate fi transmis în NetworkCapabilities pentru obținerea de informații detaliate: tipul de transport, starea metered, roaming, capacitatea de a accesa internetul și alte caracteristici.

registerDefaultNetworkCallback() (API 24+) — modul preferat de monitorizare a rețelei. Aplicația înregistrează un callback care este apelat la orice modificare a rețelei implicite (rețeaua prin care aplicația trimite trafic). Callback-ul primește un obiect Network care poate fi utilizat pentru legarea socket-urilor și a clienților HTTP. Această metodă înlocuiește învechitul getActiveNetworkInfo() și asigură monitorizarea reactivă a rețelei fără polling.

registerNetworkCallback() (API 21+) permite abonarea la modificări ale unui anumit tip de rețea prin NetworkRequest. De exemplu, aplicația poate urmări doar rețelele Wi-Fi prin new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build(). Sistemul va notifica aplicația despre conectarea/deconectarea de la Wi-Fi, fără a afecta evenimentele rețelei mobile. NetworkCapabilities.getLinkDownstreamBandwidthKbps() returnează lățimea de bandă estimată a canalului downstream în kbps, permițând adaptarea calității conținutului la viteza conexiunii.

ConnectivityManager în Jetpack Compose

Biblioteca Jetpack Connectivity (androidx.core:core-ktx) oferă extensii convenabile pentru lucrul cu ConnectivityManager în Compose. Funcția ConnectivityManager.observeAsState() returnează State<Boolean> care se actualizează la modificarea rețelei. Componenta @Composable NetworkStatus() afișează starea conexiunii și se redesenează automat la modificări. Acest lucru scutește dezvoltatorul de gestionarea manuală a callback-urilor și a ciclului de viață Activity/Fragment.

NetworkCallback și gestionarea schimbărilor rețelei

ConnectivityManager.NetworkCallback — este o clasă abstractă cu metode apelate de sistem la modificarea stării rețelei. onAvailable(Network) — se apelează când rețeaua devine disponibilă. Aplicația primește un obiect Network care poate fi utilizat pentru legarea socket-urilor prin Network.bindSocket(). onLost(Network) — se apelează când rețeaua devine indisponibilă. Aplicația trebuie să comute la date locale sau să afișeze un mesaj despre lipsa conexiunii. onCapabilitiesChanged(Network, NetworkCapabilities) — se apelează la modificarea caracteristicilor rețelei (de exemplu, la comutarea de la Wi-Fi la date mobile).

Gestionarea corectă a schimbărilor rețelei necesită luarea în considerare a ciclului de viață al componentei. Callback-ul trebuie înregistrat în onStart()/onResume() și anulat în onStop()/onPause(). Dacă callback-ul nu este anulat, acesta poate fi apelat după distrugerea Activity, ceea ce duce la scurgeri de memorie. În arhitectura Jetpack ViewModel se recomandă utilizarea lifecycleScope pentru înregistrarea callback-ului, astfel încât să fie anulat automat la curățarea ViewModel-ului. Pentru servicii și sarcini de fundal se utilizează WorkManager cu restricția NetworkType.

Gestionarea portalurilor captive — o capacitate importantă a ConnectivityManager începând cu Android 10. CAPTIVE_PORTAL — scenariul în care rețeaua Wi-Fi este disponibilă dar necesită autentificare printr-o pagină web (aeroporturi, hoteluri, cafenele). NetworkCapabilities.NET_CAPABILITY_VALIDATED indică faptul că rețeaua are acces complet la internet. Dacă NET_CAPABILITY_VALIDATED lipsește, aplicația poate deschide browserul pentru autentificare prin portalul captiv. Pentru detectarea portalului captiv se utilizează metoda isCaptivePortal(), adăugată în Android 11 (API 30).

Rețea pentru scopuri specifice (NetworkRequest)

ConnectivityManager permite solicitarea unei rețele pentru scopuri specifice prin requestNetwork() și bindProcessToNetwork(). De exemplu, o aplicație pentru descărcarea fișierelor mari poate solicita o rețea Wi-Fi chiar dacă rețeaua mobilă este activă. În acest scop se creează un NetworkRequest cu addTransportType(TRANSPORT_WIFI), iar la apariția Wi-Fi-ului sistemul apelează onAvailable(). Aplicația leagă socket-urile de această rețea prin network.bindSocket() sau OkHttp cu un obiect Network configurat. Acest lucru oferă un control flexibil asupra utilizării interfețelor de rețea.

Exemplu de implementare în Kotlin

Să examinăm un exemplu complet de utilizare a ConnectivityManager cu API modern (NetworkCallback) în arhitectura Clean Architecture. NetworkMonitor — o clasă wrapper peste ConnectivityManager care oferă starea reactivă a rețelei prin StateFlow. ViewModel se abonează la acest Flow și transmite starea în UI. Repository utilizează NetworkMonitor pentru luarea deciziilor privind solicitările de rețea. Această abordare asigură testabilitatea și izolarea dependențelor de platformă.

Exemplul de mai jos arată cum să utilizați corect ConnectivityManager cu registerDefaultNetworkCallback. Clasa NetworkMonitor încapsulează lucrul cu serviciul de sistem și oferă un Kotlin Flow<Boolean> curat. Înregistrează callback-ul la pornire și îl anulează la încheierea ciclului de viață. Lucrul asincron este asigurat prin corutine și callbackFlow — o punte între stilul callback al ConnectivityManager și stilul Flow reactiv al 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
        )
    }
}

Utilizarea NetworkMonitor în ViewModel și Repository

ViewModel se abonează la NetworkMonitor.isOnline prin stateIn() și transmite starea în Compose. Repository verifică valoarea curentă a isOnline.value înainte de apelarea API: dacă este false — returnează Flow din Room. Dacă este true — apelează API, salvează rezultatul în Room și returnează Flow din Room. WorkManager utilizează NetworkType.CONNECTED pentru limitarea sarcinilor de fundal. Testarea NetworkMonitor se realizează cu un obiect mock ConnectivityManager și fake NetworkCallback, permițând emularea oricăror scenarii de rețea în testele unitare.

Best Practices și greșeli frecvente

Prima regulă de lucru cu ConnectivityManager — nu utilizați API-ul învechit. getActiveNetworkInfo() este deprecated de la API 29 și poate returna date incorecte pe versiunile noi de Android. În locul lui utilizați getActiveNetwork() + getNetworkCapabilities() pentru verificarea unică și registerDefaultNetworkCallback() pentru monitorizarea continuă. Metoda veche nu face distincție între rețelele cu portal captiv și internetul complet, ceea ce duce la rezultate false.

A doua regulă — anulați întotdeauna înregistrarea callback-ului. Dacă Activity înregistrează NetworkCallback în onStart() dar nu anulează în onStop(), callback-ul continuă să funcționeze după distrugerea Activity. Acest lucru cauzează scurgeri de memorie și un potențial NullPointerException când callback-ul încearcă să actualizeze UI-ul componentei distruse. Utilizați lifecycleScope sau repeatOnLifecycle pentru gestionarea automată a înregistrării. În Jetpack Compose utilizați DisposableEffect pentru înregistrarea și anularea callback-ului.

A treia greșeală frecventă — verificarea doar a existenței rețelei fără a lua în considerare calitatea acesteia. Simplu „există internet" nu este suficient pentru luarea deciziilor. Aplicația trebuie să verifice NET_CAPABILITY_NOT_METERED pentru descărcarea fișierelor mari, NET_CAPABILITY_NOT_ROAMING pentru sincronizarea în fundal, NET_CAPABILITY_VALIDATED pentru confirmarea accesului la internet. Ignorarea acestor flag-uri duce la încercarea aplicației de a încărca videoclipuri în roaming sau de a sincroniza date prin portalul captiv al hotelului.

A patra — nu utilizați ConnectivityManager pentru verificarea disponibilității unui server specific. ConnectivityManager raportează starea rețelei pe dispozitiv, dar nu garantează că serverul este disponibil. Pentru verificarea disponibilității API utilizați o solicitare HTTP cu timeout scurt sau Health Check. ConnectivityManager + ping HTTP este o combinație fiabilă: mai întâi se verifică existența rețelei, apoi se execută o solicitare ușoară către server pentru confirmarea disponibilității reale.

Testarea ConnectivityManager

Pentru testele unitare utilizați Robolectric cu ShadowConnectivityManager, care permite emularea stării rețelei. Pentru testele de integrare — Android Test Orchestrator cu comutarea modului Avion. În teste verificați scenariile: trecerea din online în offline, apariția Wi-Fi-ului când rețeaua mobilă este activă, pierderea rețelei în timpul executării unei solicitări, portal captiv, roaming. Pentru mocking în testele modulare utilizați o interfață wrapper (de exemplu, NetworkMonitorInterface) care poate fi înlocuită cu un obiect mock fără dependențe de platformă.