Connectivity Manager: mi ez, módszerek és a kapcsolat figyelése

Mi az a Connectivity Manager?

A ConnectivityManager — az Android operációs rendszer rendszerszolgáltatása, amely a Context.getSystemService(Context.CONNECTIVITY_SERVICE) segítségével érhető el. API-t biztosít az eszköz hálózati kapcsolatával kapcsolatos információk lekéréséhez, a hálózati változások figyeléséhez és az alkalmazás hálózati kéréseinek kezeléséhez. A Connectivity Manager a platform első verziójától (API Level 1) kezdve az Android Framework része, és az évtizedek során jelentős változásokon ment keresztül: az egyszerű getActiveNetworkInfo()-tól a modern reaktív modellig NetworkCallback és NetworkRequest segítségével.

A Connectivity Manager fő képességei közé tartozik: az aktív hálózati kapcsolat meglétének ellenőrzése, a hálózat típusának meghatározása (Wi-Fi, mobil adat, Ethernet, Bluetooth, VPN), a hálózati állapot változásainak valós idejű figyelése, információ a sávszélességről és késleltetésről, az alkalmazás hálózati kéréseinek kezelése. A ConnectivityManager a WorkManager és Repository mellett használatos az Offline-First architektúra, az adaptív tartalom betöltés és az alkalmazás működésének optimalizálása érdekében a kapcsolat minőségétől függően.

Az Android 10-től (API 29) kezdve a Google megváltoztatta a ConnectivityManager-rel való munkavégzés megközelítését. A getActiveNetworkInfo() metódus elavulttá (deprecated) vált, helyette a registerDefaultNetworkCallback() vagy a registerNetworkCallback() használata javasolt NetworkRequest segítségével. Az új API részletesebb információkat nyújt a hálózatról, beleértve a captive portálok (hitelesítést igénylő Wi-Fi) észlelésének lehetőségét és a kapcsolat minőségének értékelését. A ConnectivityManager a Jetpack családdal is integrált: a ConnectivityManager könyvtár 2024-ben jelent meg a Jetpack részeként a hálózatfigyelés egyszerűsítésére Compose alkalmazásokban.

A Connectivity Manager szerepe az alkalmazás architektúrájában

A modern Android architektúrában a Connectivity Manager repository vagy UseCase szinten használatos a hálózati kérésekkel kapcsolatos döntések meghozatalához. A Repository réteg ellenőrzi a hálózat állapotát az API meghívása előtt: ha a hálózat nem elérhető, a helyi tárolóból (Room) származó adatok kerülnek visszaadásra. Ha a hálózat elérhető, a kérés a szerverhez kerül elküldésre, és az eredmény a Room-ban tárolódik. A ViewModel a Room-ból származó Flow-ra fizet elő, és nem ismeri a hálózati interakció részleteit — ez lehetővé teszi az egyes rétegek független tesztelését.

Hogyan működik a Connectivity Manager

A Connectivity Manager a hálózati állapotra vonatkozó információkat a connectivity rendszerszolgáltatástól kapja, amely a Linux kernel hálózati interfészeivel kommunikál. Amikor az eszköz csatlakozik Wi-Fi-hez vagy bekapcsolja a mobil adatokat, a kernel értesíti a rendszerszolgáltatást, amely frissíti a belső állapotot és értesíti az összes regisztrált callbacket. Az architektúra a ConnectivityManager az Observer mintára épül: az alkalmazás regisztrálja a NetworkCallback-ot, és értesítéseket kap a hálózat bármilyen változásáról — a kapcsolat megjelenéséről, elvesztéséről, a hálózat típusának változásáról vagy a minőség romlásáról.

A modern ConnectivityManager API a NetworkRequest segítségével szűri a hálózati eseményeket. A NetworkRequest lehetővé teszi a hálózatra vonatkozó követelmények meghatározását: szállítási mód (Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET), internetelérési képesség (NetworkCapabilities.NET_CAPABILITY_INTERNET) és egyéb kritériumok. Ha egy alkalmazásnak csak Wi-Fi-re van szüksége nagy fájlok letöltéséhez, létrehoz egy NetworkRequest-et Transport.WIFI-vel és regisztrál egy callbacket. A rendszer csak a Wi-Fi kapcsolat változásakor értesíti az alkalmazást, figyelmen kívül hagyva a mobilhálózat eseményeit.

A Connectivity Manager fontos jellemzője Android 12+-on a capabilities-based networking. Az alkalmazás nem csak azt ellenőrzi, hogy "van-e internet", hanem fel tudja mérni, hogy milyen típusú forgalom érhető el. Például a NET_CAPABILITY_NOT_METERED korlátlan kapcsolatot jelez (Wi-Fi), a NET_CAPABILITY_NOT_ROAMING — hogy az eszköz nincs roamingban. Ez lehetővé teszi döntések meghozatalát: videók betöltése csak Wi-Fi-n keresztül, szinkronizálás elhalasztása roamingban, vagy mobil adat használata csak kritikus kérésekhez.

Engedélyek a Connectivity Manager-hez

A Connectivity Manager használatához Android alkalmazásban engedélyek szükségesek. ACCESS_NETWORK_STATE — kötelező engedély a hálózati információk olvasásához, az AndroidManifest.xml-ben deklarálva. Ezen engedély nélkül a ConnectivityManager null-t ad vissza a getActiveNetwork()-hez, és nem hívja meg a callbackeket. A hálózati műveletek végrehajtásához INTERNET engedély is szükséges. Az Android 10-től (API 29) kezdve az alkalmazás további runtime engedélyek nélkül ellenőrizheti a hálózat állapotát — az ACCESS_NETWORK_STATE normál engedély (normal permission), amely automatikusan megadásra kerül a telepítéskor.

A Connectivity Manager fő metódusai

A modern Connectivity Manager több kulcsfontosságú metódust kínál a hálózattal való munkához. A getActiveNetwork() (API 23+) visszaadja az aktuális aktív hálózat Network objektumát, vagy null-t, ha az eszköz nincs csatlakoztatva. Ez a metódus nem igényel callbackeket, és egyszeri ellenőrzéshez alkalmas. A Network objektum továbbítható a NetworkCapabilities-be részletes információkhoz: szállítási típus, metered állapot, roaming, internetelérési képesség és egyéb jellemzők.

A registerDefaultNetworkCallback() (API 24+) — a hálózatfigyelés előnyben részesített módja. Az alkalmazás regisztrál egy callbacket, amely az alapértelmezett hálózat (amelyen keresztül az alkalmazás forgalmat küld) bármilyen változásakor meghívódik. A callback egy Network objektumot kap, amely socketek és HTTP kliensek kötésére használható. Ez a metódus felváltja az elavult getActiveNetworkInfo()-t, és reaktív hálózatfigyelést biztosít polling nélkül.

A registerNetworkCallback() (API 21+) lehetővé teszi egy adott hálózattípus változásaira való feliratkozást a NetworkRequest segítségével. Például az alkalmazás csak Wi-Fi hálózatokat követhet nyomon a new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build() segítségével. A rendszer értesíti az alkalmazást a Wi-Fi csatlakozásról/lekapcsolódásról anélkül, hogy befolyásolná a mobilhálózat eseményeit. A NetworkCapabilities.getLinkDownstreamBandwidthKbps() visszaadja a downstream csatorna becsült sávszélességét kbps-ben, lehetővé téve a tartalom minőségének a kapcsolat sebességéhez való igazítását.

ConnectivityManager a Jetpack Compose-ban

A Jetpack Connectivity könyvtár (androidx.core:core-ktx) kényelmes bővítményeket kínál a ConnectivityManager használatához Compose-ban. A ConnectivityManager.observeAsState() függvény egy State<Boolean> értéket ad vissza, amely a hálózat változásakor frissül. A @Composable NetworkStatus() komponens megjeleníti a kapcsolat állapotát, és automatikusan újrarajzolódik változások esetén. Ez megszabadítja a fejlesztőt a callbackek és az Activity/Fragment életciklus kézi kezelésétől.

NetworkCallback és a hálózati változások kezelése

A ConnectivityManager.NetworkCallback — egy absztrakt osztály metódusokkal, amelyeket a rendszer hív meg a hálózat állapotának változásakor. onAvailable(Network) — akkor hívódik meg, amikor a hálózat elérhetővé válik. Az alkalmazás egy Network objektumot kap, amely socketek kötésére használható a Network.bindSocket() segítségével. onLost(Network) — akkor hívódik meg, amikor a hálózat elérhetetlenné válik. Az alkalmazásnak helyi adatokra kell váltania, vagy meg kell jelenítenie egy üzenetet a kapcsolat hiányáról. onCapabilitiesChanged(Network, NetworkCapabilities) — a hálózat jellemzőinek megváltozásakor hívódik meg (például Wi-Fi-ről mobil adatra váltáskor).

A hálózati változások helyes kezelése megköveteli a komponens életciklusának figyelembevételét. A callbacket regisztrálni kell az onStart()/onResume() metódusokban, és visszavonni az onStop()/onPause() metódusokban. Ha a callback nincs visszavonva, az Activity megsemmisítése után is meghívódhat, ami memóriaszivárgáshoz vezet. A Jetpack ViewModel architektúrában javasolt a lifecycleScope használata a callback regisztrálásához, hogy az automatikusan visszavonásra kerüljön a ViewModel tisztításakor. Szolgáltatásokhoz és háttérfeladatokhoz a WorkManager használatos NetworkType korlátozással.

A captive portálok kezelése — a ConnectivityManager fontos képessége az Android 10-től kezdve. CAPTIVE_PORTAL — az a forgatókönyv, amikor a Wi-Fi hálózat elérhető, de hitelesítést igényel egy weboldalon keresztül (repülőterek, hotelek, kávézók). A NetworkCapabilities.NET_CAPABILITY_VALIDATED jelzi, hogy a hálózat teljes internet-hozzáféréssel rendelkezik. Ha a NET_CAPABILITY_VALIDATED hiányzik, az alkalmazás megnyithatja a böngészőt a captive portálon keresztüli hitelesítéshez. A captive portál észleléséhez az isCaptivePortal() metódus használatos, amely az Android 11-ben (API 30) került hozzáadásra.

Hálózat speciális célokra (NetworkRequest)

A ConnectivityManager lehetővé teszi hálózat kérését speciális célokra a requestNetwork() és a bindProcessToNetwork() segítségével. Például egy nagy fájlok letöltésére szolgáló alkalmazás kérhet Wi-Fi hálózatot, még ha a mobilhálózat aktív is. Ehhez létrejön egy NetworkRequest addTransportType(TRANSPORT_WIFI) paraméterrel, és amikor a Wi-Fi megjelenik, a rendszer meghívja az onAvailable()-t. Az alkalmazás socketeket köt ehhez a hálózathoz a network.bindSocket() vagy az OkHttp segítségével egy konfigurált Network objektummal. Ez rugalmas irányítást biztosít a hálózati interfészek használata felett.

Megvalósítási példa Kotlinban

Nézzünk egy teljes példát a ConnectivityManager használatára a modern API-val (NetworkCallback) a Clean Architecture-ban. NetworkMonitor — egy wrapper osztály a ConnectivityManager körül, amely reaktív hálózati állapotot biztosít a StateFlow segítségével. A ViewModel feliratkozik erre a Flow-ra, és továbbítja az állapotot a UI-nak. A Repository a NetworkMonitor segítségével hoz döntéseket a hálózati kérésekről. Ez a megközelítés tesztelhetőséget és a platformfüggőségek elkülönítését biztosítja.

Az alábbi példa bemutatja, hogyan kell helyesen használni a ConnectivityManager-t a registerDefaultNetworkCallback segítségével. A NetworkMonitor osztály bekapszulázza a rendszerszolgáltatással való munkát, és tiszta Kotlin Flow<Boolean> értéket biztosít. Regisztrálja a callbacket induláskor, és visszavonja az életciklus végén. Az aszinkron munkát korutinok és callbackFlow biztosítják — híd a ConnectivityManager callback stílusa és a Kotlin reaktív Flow stílusa között.

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

A NetworkMonitor használata ViewModel-ben és Repository-ban

A ViewModel feliratkozik a NetworkMonitor.isOnline értékre a stateIn() segítségével, és továbbítja az állapotot a Compose-nak. A Repository ellenőrzi az isOnline.value aktuális értékét az API meghívása előtt: ha false — Flow-t ad vissza a Room-ból. Ha true — meghívja az API-t, elmenti az eredményt a Room-ba, és Flow-t ad vissza a Room-ból. A WorkManager a NetworkType.CONNECTED használatával korlátozza a háttérfeladatokat. A NetworkMonitor tesztelése mock ConnectivityManager objektummal és fake NetworkCallback segítségével történik, lehetővé téve bármilyen hálózati forgatókönyv emulálását a egységtesztekben.

Best Practices és gyakori hibák

Az első szabály a ConnectivityManager-rel való munkához — ne használja az elavult API-t. A getActiveNetworkInfo() az API 29 óta deprecated, és pontatlan adatokat adhat vissza az Android új verzióin. Helyette használja a getActiveNetwork() + getNetworkCapabilities() kombinációt egyszeri ellenőrzéshez, és a registerDefaultNetworkCallback()-ot folyamatos figyeléshez. A régi metódus nem tesz különbséget a captive portállal rendelkező és a teljes internet-hozzáféréssel rendelkező hálózatok között, ami téves pozitív eredményekhez vezet.

Második szabály — mindig vonja vissza a callback regisztrációját. Ha az Activity regisztrál egy NetworkCallback-ot az onStart()-ban, de nem vonja vissza az onStop()-ban, a callback tovább működik az Activity megsemmisítése után. Ez memóriaszivárgást és potenciális NullPointerException-t okoz, amikor a callback megpróbálja frissíteni a megsemmisített komponens UI-ját. Használja a lifecycleScope-t vagy a repeatOnLifecycle-t az automatikus regisztrációkezeléshez. Jetpack Compose-ban használja a DisposableEffect-et a callback regisztrálásához és visszavonásához.

Harmadik gyakori hiba — csak a hálózat meglétének ellenőrzése a minőség figyelembevétele nélkül. Egyszerűen "van internet" nem elegendő a döntéshozatalhoz. Az alkalmazásnak ellenőriznie kell a NET_CAPABILITY_NOT_METERED-et nagy fájlok letöltéséhez, a NET_CAPABILITY_NOT_ROAMING-et háttér-szinkronizáláshoz, és a NET_CAPABILITY_VALIDATED-et az internet-hozzáférés megerősítéséhez. Ezen jelzők figyelmen kívül hagyása ahhoz vezet, hogy az alkalmazás megpróbál videót betölteni roamingban vagy adatokat szinkronizálni egy hotel captive portálján keresztül.

Negyedik — ne használja a ConnectivityManager-t egy adott szerver elérhetőségének ellenőrzésére. A ConnectivityManager az eszköz hálózati állapotáról jelent, de nem garantálja, hogy a szerver elérhető. Az API elérhetőségének ellenőrzéséhez használjon rövid időkorlátos HTTP kérést vagy Health Check-et. A ConnectivityManager + HTTP ping megbízható kombináció: először a hálózat megléte kerül ellenőrzésre, majd egy könnyű kérés küldődik a szerverhez a tényleges elérhetőség megerősítéséhez.

A ConnectivityManager tesztelése

Egységtesztekhez használja a Robolectric-et a ShadowConnectivityManager segítségével, amely lehetővé teszi a hálózati állapot emulálását. Integrációs tesztekhez — Android Test Orchestrator a Repülőgép üzemmód váltásával. A tesztekben ellenőrizze a következő forgatókönyveket: átmenet online-ból offline-ba, Wi-Fi megjelenése aktív mobilhálózat mellett, hálózat elvesztése kérés végrehajtása közben, captive portál, roaming. A mockoláshoz moduláris tesztekben használjon wrapper interfészt (pl. NetworkMonitorInterface), amely platformfüggőségek nélkül helyettesíthető egy mock objektummal.