Connectivity Manager: co to jest, metody i monitorowanie połączenia

Co to jest Connectivity Manager?

ConnectivityManager — to systemowa usługa systemu operacyjnego Android, dostępna przez Context.getSystemService(Context.CONNECTIVITY_SERVICE). Udostępnia API do uzyskiwania informacji o połączeniu sieciowym urządzenia, monitorowania zmian sieci i zarządzania żądaniami sieciowymi aplikacji. Connectivity Manager jest częścią Android Framework od pierwszej wersji platformy (API Level 1) i przez dziesięciolecia przeszedł znaczące zmiany: od prostego getActiveNetworkInfo() do nowoczesnego modelu reaktywnego z NetworkCallback i NetworkRequest.

Główne możliwości Connectivity Manager obejmują: sprawdzanie obecności aktywnego połączenia sieciowego, określanie typu sieci (Wi-Fi, dane mobilne, Ethernet, Bluetooth, VPN), monitorowanie zmian stanu sieci w czasie rzeczywistym, uzyskiwanie informacji o przepustowości i opóźnieniach, zarządzanie żądaniami sieciowymi aplikacji. ConnectivityManager jest używany w parze z WorkManager i Repository do implementacji architektury Offline-First, adaptacyjnego ładowania treści i optymalizacji działania aplikacji w zależności od jakości połączenia.

Począwszy od Androida 10 (API 29), Google zmienił podejście do pracy z ConnectivityManager. Metoda getActiveNetworkInfo() została oznaczona jako deprecated, a zamiast niej zaleca się używanie registerDefaultNetworkCallback() lub registerNetworkCallback() z NetworkRequest. Nowe API dostarcza bardziej szczegółowe informacje o sieci, w tym możliwość wykrywania portali captive (Wi-Fi z autoryzacją) i oceny jakości połączenia. ConnectivityManager jest również zintegrowany z rodziną Jetpack: biblioteka ConnectivityManager została wydana w 2024 roku jako część Jetpack do uproszczenia monitorowania sieci w aplikacjach Compose.

Rola Connectivity Manager w architekturze aplikacji

W nowoczesnej architekturze Androida Connectivity Manager jest używany na poziomie repozytorium lub UseCase do podejmowania decyzji o żądaniach sieciowych. Warstwa repozytorium sprawdza stan sieci przed wywołaniem API: jeśli sieć jest niedostępna, zwracane są dane z lokalnego magazynu (Room). Jeśli sieć jest dostępna, wykonywane jest żądanie do serwera, a wynik jest zapisywany w Room. ViewModel subskrybuje Flow z Room i nie zna szczegółów interakcji sieciowej — pozwala to łatwo testować każdą warstwę niezależnie.

Jak działa Connectivity Manager

Connectivity Manager otrzymuje informacje o stanie sieci od systemowej usługi connectivity, która komunikuje się z interfejsami sieciowymi jądra Linux. Gdy urządzenie łączy się z Wi-Fi lub włącza dane mobilne, jądro powiadamia usługę systemową, która aktualizuje stan wewnętrzny i powiadamia wszystkie zarejestrowane callbacki. Architektura ConnectivityManager jest zbudowana na wzorcu Observer: aplikacja rejestruje NetworkCallback i otrzymuje powiadomienia o wszelkich zmianach sieci — pojawieniu się połączenia, jego utracie, zmianie typu sieci lub pogorszeniu jakości.

Nowoczesne API ConnectivityManager używa NetworkRequest do filtrowania zdarzeń sieciowych. NetworkRequest pozwala określić wymagania wobec sieci: transport (Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET), możliwość dostępu do Internetu (NetworkCapabilities.NET_CAPABILITY_INTERNET) i inne kryteria. Jeśli aplikacja potrzebuje tylko Wi-Fi do pobierania dużych plików, tworzy NetworkRequest z Transport.WIFI i rejestruje callback. System powiadomi aplikację tylko przy zmianie połączenia Wi-Fi, ignorując zdarzenia sieci mobilnej.

Ważna cecha Connectivity Manager na Android 12+ to capabilities-based networking. Aplikacja nie tylko sprawdza „czy jest Internet”, ale może ocenić, jaki rodzaj ruchu jest dostępny. Na przykład NET_CAPABILITY_NOT_METERED wskazuje na połączenie nielimitowane (Wi-Fi), NET_CAPABILITY_NOT_ROAMING — że urządzenie nie jest w roamingu. Pozwala to podejmować decyzje: ładować wideo tylko przez Wi-Fi, odkładać synchronizację w roamingu lub używać danych mobilnych tylko do krytycznych żądań.

Uprawnienia dla Connectivity Manager

Do korzystania z Connectivity Manager w aplikacji Android wymagane są uprawnienia. ACCESS_NETWORK_STATE — obowiązkowe uprawnienie do odczytu informacji o sieci, deklarowane w AndroidManifest.xml. Bez tego uprawnienia ConnectivityManager zwróci null dla getActiveNetwork() i nie będzie wywoływać callbacków. Do wykonywania operacji sieciowych wymagane jest również uprawnienie INTERNET. Począwszy od Androida 10 (API 29), aplikacja może sprawdzać stan sieci bez dodatkowych uprawnień runtime — ACCESS_NETWORK_STATE jest uprawnieniem normalnym i jest przyznawane automatycznie podczas instalacji.

Główne metody Connectivity Manager

Nowoczesny Connectivity Manager udostępnia kilka kluczowych metod do pracy z siecią. getActiveNetwork() (API 23+) zwraca obiekt Network bieżącej aktywnej sieci lub null, jeśli urządzenie nie jest podłączone. Ta metoda nie wymaga callbacków i nadaje się do jednorazowego sprawdzenia. Obiekt Network można przekazać do NetworkCapabilities w celu uzyskania szczegółowych informacji: typ transportu, status metered, roaming, możliwość dostępu do Internetu i inne charakterystyki.

registerDefaultNetworkCallback() (API 24+) — preferowany sposób monitorowania sieci. Aplikacja rejestruje callback, który jest wywoływany przy wszelkich zmianach sieci domyślnej (sieci, przez którą aplikacja wysyła ruch). Callback otrzymuje obiekt Network, który można użyć do wiązania gniazd i klientów HTTP. Ta metoda zastępuje przestarzały getActiveNetworkInfo() i zapewnia reaktywne monitorowanie sieci bez pollingu.

registerNetworkCallback() (API 21+) pozwala subskrybować zmiany określonego typu sieci przez NetworkRequest. Na przykład aplikacja może śledzić tylko sieci Wi-Fi przez new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build(). System będzie powiadamiać aplikację o podłączeniu/odłączeniu od Wi-Fi, nie wpływając na zdarzenia sieci mobilnej. NetworkCapabilities.getLinkDownstreamBandwidthKbps() zwraca oszacowaną przepustowość kanału下行 w kbps, co pozwala dostosować jakość treści do prędkości połączenia.

ConnectivityManager w Jetpack Compose

Biblioteka Jetpack Connectivity (androidx.core:core-ktx) udostępnia wygodne rozszerzenia do pracy z ConnectivityManager w Compose. Funkcja ConnectivityManager.observeAsState() zwraca State, który aktualizuje się przy zmianie sieci. Komponent @Composable NetworkStatus() wyświetla status połączenia i automatycznie przerysowuje się przy zmianach. To zwalnia programistę z ręcznego zarządzania callbackami i cyklem życia Activity/Fragment.

NetworkCallback i obsługa zmian sieci

ConnectivityManager.NetworkCallback — to abstrakcyjna klasa z metodami wywoływanymi przez system przy zmianie stanu sieci. onAvailable(Network) — wywoływane, gdy sieć staje się dostępna. Aplikacja otrzymuje obiekt Network, który można użyć do wiązania gniazd przez Network.bindSocket(). onLost(Network) — wywoływane, gdy sieć staje się niedostępna. Aplikacja powinna przełączyć się na dane lokalne lub wyświetlić komunikat o braku połączenia. onCapabilitiesChanged(Network, NetworkCapabilities) — wywoływane przy zmianie charakterystyk sieci (na przykład przy przełączaniu z Wi-Fi na dane mobilne).

Prawidłowa obsługa zmian sieci wymaga uwzględnienia cyklu życia komponentu. Callback powinien być zarejestrowany w onStart()/onResume() i anulowany w onStop()/onPause(). Jeśli callback nie zostanie anulowany, może być wywoływany po zniszczeniu Activity, co prowadzi do wycieku pamięci. W architekturze Jetpack ViewModel zaleca się używanie lifecycleScope do rejestracji callbacka, aby automatycznie anulował się przy czyszczeniu ViewModel. Dla usług i zadań w tle używany jest WorkManager z ograniczeniem NetworkType.

Obsługa portali captive — ważna możliwość ConnectivityManager począwszy od Androida 10. CAPTIVE_PORTAL — scenariusz, gdy sieć Wi-Fi jest dostępna, ale wymaga autoryzacji przez stronę internetową (lotniska, hotele, kawiarnie). NetworkCapabilities.NET_CAPABILITY_VALIDATED wskazuje, że sieć ma pełny dostęp do Internetu. Jeśli NET_CAPABILITY_VALIDATED jest nieobecne, aplikacja może otworzyć przeglądarkę w celu autoryzacji przez portal captive. Do wykrywania portalu captive używana jest metoda isCaptivePortal(), dodana w Android 11 (API 30).

Sieć do określonych celów (NetworkRequest)

ConnectivityManager pozwala żądać sieci do konkretnych celów przez requestNetwork() i bindProcessToNetwork(). Na przykład aplikacja do pobierania dużych plików może zażądać sieci Wi-Fi nawet jeśli aktywna jest sieć mobilna. W tym celu tworzy się NetworkRequest z addTransportType(TRANSPORT_WIFI), a gdy pojawi się Wi-Fi, system wywołuje onAvailable(). Aplikacja wiąże gniazda z tą siecią przez network.bindSocket() lub OkHttp z skonfigurowanym obiektem Network. Daje to elastyczną kontrolę nad używaniem interfejsów sieciowych.

Przykład implementacji w Kotlin

Rozważmy pełny przykład użycia ConnectivityManager z nowoczesnym API (NetworkCallback) w architekturze Clean Architecture. NetworkMonitor — klasa otaczająca ConnectivityManager, która udostępnia reaktywny status sieci przez StateFlow. ViewModel subskrybuje ten Flow i przekazuje stan do UI. Repository używa NetworkMonitor do podejmowania decyzji o żądaniach sieciowych. Takie podejście zapewnia testowalność i izolację zależności platformowych.

Poniższy przykład pokazuje, jak prawidłowo używać ConnectivityManager z registerDefaultNetworkCallback. Klasa NetworkMonitor enkapsuluje pracę z usługą systemową i udostępnia czysty Kotlin Flow. Rejestruje callback przy starcie i anuluje go przy zakończeniu cyklu życia. Asynchroniczna praca jest zapewniona przez korutyny i callbackFlow — most między stylem callbackowym ConnectivityManager a reaktywnym stylem Flow 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
        )
    }
}

Użycie NetworkMonitor w ViewModel i Repository

ViewModel subskrybuje NetworkMonitor.isOnline przez stateIn() i przekazuje stan do Compose. Repository sprawdza bieżącą wartość isOnline.value przed wywołaniem API: jeśli false — zwraca Flow z Room. Jeśli true — wywołuje API, zapisuje wynik w Room i zwraca Flow z Room. WorkManager używa NetworkType.CONNECTED do ograniczania zadań w tle. Testowanie NetworkMonitor wykonuje się z mock-objektem ConnectivityManager i fake NetworkCallback, co pozwala emulować dowolne scenariusze sieciowe w testach jednostkowych.

Best Practices i częste błędy

Pierwsza zasada pracy z ConnectivityManager — nie używać przestarzałego API. getActiveNetworkInfo() jest deprecated od API 29 i może zwracać nieprawidłowe dane na nowych wersjach Androida. Zamiast niego używaj getActiveNetwork() + getNetworkCapabilities() do jednorazowego sprawdzenia i registerDefaultNetworkCallback() do ciągłego monitorowania. Stara metoda nie rozróżnia sieci z portalem captive i pełnym dostępem do Internetu, co prowadzi do fałszywych wyników.

Druga zasada — zawsze anulować rejestrację callbacka. Jeśli Activity rejestruje NetworkCallback w onStart(), ale nie anuluje w onStop(), callback działa po zniszczeniu Activity. Powoduje to wyciek pamięci i potencjalny NullPointerException, gdy callback próbuje zaktualizować UI zniszczonego komponentu. Używaj lifecycleScope lub repeatOnLifecycle do automatycznego zarządzania rejestracją. W Jetpack Compose używaj DisposableEffect do rejestracji i anulowania callbacka.

Trzeci częsty błąd — sprawdzanie tylko obecności sieci bez uwzględnienia jej jakości. Proste „jest Internet” nie wystarcza do podejmowania decyzji. Aplikacja powinna sprawdzać NET_CAPABILITY_NOT_METERED do pobierania dużych plików, NET_CAPABILITY_NOT_ROAMING do synchronizacji w tle, NET_CAPABILITY_VALIDATED do potwierdzenia dostępu do Internetu. Ignorowanie tych flag prowadzi do tego, że aplikacja próbuje ładować wideo w roamingu lub synchronizować dane przez portal captive hotelu.

Czwarte — nie używać ConnectivityManager do sprawdzania dostępności konkretnego serwera. ConnectivityManager informuje o stanie sieci na urządzeniu, ale nie gwarantuje, że serwer jest dostępny. Do sprawdzania dostępności API używaj żądania HTTP z krótkim timeoutem lub Health Check. ConnectivityManager + ping HTTP to niezawodna kombinacja: najpierw sprawdzana jest obecność sieci, następnie wykonywane jest lekkie żądanie do serwera w celu potwierdzenia rzeczywistej dostępności.

Testowanie ConnectivityManager

Do testów jednostkowych używaj Robolectric z ShadowConnectivityManager, który pozwala emulować stan sieci. Do testów integracyjnych — Android Test Orchestrator z przełączaniem trybu samolotowego. W testach sprawdzaj scenariusze: przejście z online do offline, pojawienie się Wi-Fi przy aktywnej sieci mobilnej, utrata sieci podczas wykonywania żądania, portal captive, roaming. Do mockowania w testach modułowych używaj interfejsu otaczającego (np. NetworkMonitorInterface), który można zastąpić mock-objektem bez zależności platformowych.