Connectivity Manager: Was es ist, Methoden und Verbindungsüberwachung

Was ist Connectivity Manager?

ConnectivityManager ist ein Systemdienst des Android-Betriebssystems, der über Context.getSystemService(Context.CONNECTIVITY_SERVICE) zugänglich ist. Er bietet eine API zum Abrufen von Informationen über die Netzwerkverbindung des Geräts, zur Überwachung von Netzwerkänderungen und zur Verwaltung der Netzwerkanfragen der Anwendung. Connectivity Manager ist seit der ersten Plattformversion (API Level 1) Teil des Android Frameworks und hat im Laufe der Jahrzehnte bedeutende Veränderungen durchgemacht: vom einfachen getActiveNetworkInfo() bis zum modernen reaktiven Modell mit NetworkCallback und NetworkRequest.

Zu den Hauptfunktionen von Connectivity Manager gehören: Überprüfung einer aktiven Netzwerkverbindung, Bestimmung des Netzwerktyps (Wi-Fi, mobile Daten, Ethernet, Bluetooth, VPN), Echtzeit-Überwachung von Netzwerkzustandsänderungen, Abruf von Informationen über Bandbreite und Latenz sowie Verwaltung der Netzwerkanfragen der Anwendung. ConnectivityManager wird zusammen mit WorkManager und Repository verwendet, um eine Offline-First-Architektur, adaptives Laden von Inhalten und eine Optimierung der Anwendung basierend auf der Verbindungsqualität zu implementieren.

Ab Android 10 (API 29) hat Google den Ansatz für die Arbeit mit ConnectivityManager geändert. Die Methode getActiveNetworkInfo() wurde als veraltet erklärt, stattdessen wird die Verwendung von registerDefaultNetworkCallback() oder registerNetworkCallback() mit NetworkRequest empfohlen. Die neue API bietet detailliertere Netzwerkinformationen, einschließlich der Erkennung von Captive Portals (Wi-Fi mit Authentifizierung) und der Bewertung der Verbindungsqualität. ConnectivityManager ist auch in die Jetpack-Familie integriert: Die ConnectivityManager-Bibliothek wurde 2024 als Teil von Jetpack veröffentlicht, um die Netzwerküberwachung in Compose-Anwendungen zu vereinfachen.

Die Rolle von Connectivity Manager in der Anwendungsarchitektur

In der modernen Android-Architektur wird ConnectivityManager auf Repository- oder UseCase-Ebene verwendet, um Entscheidungen über Netzwerkanfragen zu treffen. Die Repository-Schicht überprüft den Netzwerkstatus vor dem API-Aufruf: Ist das Netzwerk nicht verfügbar, werden Daten aus dem lokalen Speicher (Room) zurückgegeben. Ist das Netzwerk verfügbar, wird eine Anfrage an den Server gestellt und das Ergebnis in Room gespeichert. Das ViewModel abonniert einen Flow aus Room und kennt die Details der Netzwerkinteraktion nicht — dies ermöglicht das unabhängige Testen jeder Schicht.

Wie Connectivity Manager funktioniert

Connectivity Manager bezieht Netzwerkzustandsinformationen vom connectivity-Systemdienst, der mit den Netzwerkschnittstellen des Linux-Kernels interagiert. Wenn das Gerät eine Wi-Fi-Verbindung herstellt oder mobile Daten aktiviert, benachrichtigt der Kernel den Systemdienst, der seinen internen Zustand aktualisiert und alle registrierten Callbacks benachrichtigt. Die Architektur von ConnectivityManager basiert auf dem Observer-Muster: Die Anwendung registriert einen NetworkCallback und erhält Benachrichtigungen über alle Netzwerkänderungen — Verbindungsaufbau, Verbindungsverlust, Netzwerktypwechsel oder Qualitätsverschlechterung.

Die moderne ConnectivityManager-API verwendet NetworkRequest zum Filtern von Netzwerkereignissen. NetworkRequest ermöglicht die Angabe von Anforderungen an das Netzwerk: Transport (Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET), Internetfähigkeit (NetworkCapabilities.NET_CAPABILITY_INTERNET) und andere Kriterien. Wenn eine Anwendung nur Wi-Fi zum Herunterladen großer Dateien benötigt, erstellt sie einen NetworkRequest mit Transport.WIFI und registriert einen Callback. Das System benachrichtigt die Anwendung nur bei Änderungen der Wi-Fi-Verbindung und ignoriert mobile Netzwerkereignisse.

Eine wichtige Funktion von Connectivity Manager unter Android 12+ ist fähigkeitsbasiertes Networking. Die Anwendung prüft nicht nur „Gibt es Internet?“, sondern kann bewerten, welche Art von Verkehr verfügbar ist. NET_CAPABILITY_NOT_METERED zeigt beispielsweise eine unbegrenzte Verbindung (Wi-Fi) an, NET_CAPABILITY_NOT_ROAMING zeigt an, dass sich das Gerät nicht im Roaming befindet. Dies ermöglicht Entscheidungen: Video nur über Wi-Fi herunterladen, Synchronisierung im Roaming verschieben oder mobile Daten nur für kritische Anfragen verwenden.

Berechtigungen für Connectivity Manager

Für die Verwendung von Connectivity Manager in einer Android-Anwendung sind Berechtigungen erforderlich. ACCESS_NETWORK_STATE ist eine obligatorische Berechtigung zum Lesen von Netzwerkinformationen, die in der AndroidManifest.xml deklariert wird. Ohne diese Berechtigung gibt ConnectivityManager für getActiveNetwork() null zurück und ruft keine Callbacks auf. Für Netzwerkoperationen ist auch die INTERNET-Berechtigung erforderlich. Ab Android 10 (API 29) kann die Anwendung den Netzwerkstatus ohne zusätzliche Laufzeitberechtigungen überprüfen — ACCESS_NETWORK_STATE ist eine normale Berechtigung und wird bei der Installation automatisch erteilt.

Hauptmethoden von Connectivity Manager

Der moderne Connectivity Manager bietet mehrere wichtige Methoden für die Arbeit mit dem Netzwerk. getActiveNetwork() (API 23+) gibt das Network-Objekt des aktuell aktiven Netzwerks zurück oder null, wenn das Gerät nicht verbunden ist. Diese Methode benötigt keine Callbacks und eignet sich für einmalige Überprüfungen. Das Network-Objekt kann an NetworkCapabilities übergeben werden, um detaillierte Informationen zu erhalten: Transporttyp, Metered-Status, Roaming, Internetfähigkeit und andere Eigenschaften.

registerDefaultNetworkCallback() (API 24+) ist die bevorzugte Methode zur Netzwerküberwachung. Die Anwendung registriert einen Callback, der bei Änderungen des Standardnetzwerks (dem Netzwerk, über das die Anwendung Traffic sendet) aufgerufen wird. Der Callback erhält ein Network-Objekt, das zum Binden von Sockets und HTTP-Clients verwendet werden kann. Diese Methode ersetzt das veraltete getActiveNetworkInfo() und bietet reaktive Netzwerküberwachung ohne Polling.

registerNetworkCallback() (API 21+) ermöglicht das Abonnieren von Änderungen eines bestimmten Netzwerktyps über NetworkRequest. Eine Anwendung kann beispielsweise nur Wi-Fi-Netzwerke mit new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build() verfolgen. Das System benachrichtigt die Anwendung über Wi-Fi-Verbindung/Trennung, ohne mobile Netzwerkereignisse zu beeinflussen. NetworkCapabilities.getLinkDownstreamBandwidthKbps() gibt eine Schätzung der Downstream-Bandbreite in kbit/s zurück und ermöglicht die Anpassung der Inhaltsqualität an die Verbindungsgeschwindigkeit.

ConnectivityManager in Jetpack Compose

Die Jetpack Connectivity-Bibliothek (androidx.core:core-ktx) bietet praktische Erweiterungen für die Arbeit mit ConnectivityManager in Compose. Die Funktion ConnectivityManager.observeAsState() gibt einen State zurück, der bei Netzwerkänderungen aktualisiert wird. Die @Composable NetworkStatus()-Komponente zeigt den Verbindungsstatus an und wird bei Änderungen automatisch neu gezeichnet. Dies erspart dem Entwickler die manuelle Verwaltung von Callbacks und des Activity/Fragment-Lebenszyklus.

NetworkCallback und Behandlung von Netzwerkänderungen

ConnectivityManager.NetworkCallback ist eine abstrakte Klasse mit Methoden, die vom System bei Änderungen des Netzwerkzustands aufgerufen werden. onAvailable(Network) wird aufgerufen, wenn ein Netzwerk verfügbar wird. Die Anwendung erhält ein Network-Objekt, das zum Binden von Sockets über Network.bindSocket() verwendet werden kann. onLost(Network) wird aufgerufen, wenn ein Netzwerk nicht mehr verfügbar ist. Die Anwendung sollte auf lokale Daten umschalten oder eine Meldung über fehlende Verbindung anzeigen. onCapabilitiesChanged(Network, NetworkCapabilities) wird bei Änderung der Netzwerkeigenschaften aufgerufen (z. B. beim Wechsel von Wi-Fi zu mobilen Daten).

Die korrekte Behandlung von Netzwerkänderungen erfordert die Berücksichtigung des Komponentenlebenszyklus. Der Callback muss registriert werden in onStart()/onResume() und in onStop()/onPause() aufgehoben werden. Wird der Callback nicht aufgehoben, kann er nach der Zerstörung der Activity weiterlaufen, was zu Speicherlecks und potenziellen NullPointerException führt, wenn der Callback versucht, die UI einer zerstörten Komponente zu aktualisieren. Verwenden Sie lifecycleScope oder repeatOnLifecycle für die automatische Registrierungsverwaltung. Verwenden Sie in Jetpack Compose DisposableEffect zum Registrieren und Aufheben des Callbacks.

Behandlung von Captive Portals ist eine wichtige Funktion von ConnectivityManager ab Android 10. CAPTIVE_PORTAL ist ein Szenario, bei dem ein Wi-Fi-Netzwerk verfügbar ist, aber eine Authentifizierung über eine Webseite erfordert (Flughäfen, Hotels, Cafés). NetworkCapabilities.NET_CAPABILITY_VALIDATED zeigt an, dass das Netzwerk vollen Internetzugang hat. Fehlt NET_CAPABILITY_VALIDATED, kann die Anwendung einen Browser für die Captive-Portal-Authentifizierung öffnen. Die in Android 11 (API 30) hinzugefügte Methode isCaptivePortal() wird zur Erkennung von Captive Portals verwendet.

Netzwerk für spezifische Zwecke (NetworkRequest)

ConnectivityManager ermöglicht die Anforderung eines Netzwerks für bestimmte Zwecke über requestNetwork() und bindProcessToNetwork(). Eine Anwendung zum Herunterladen großer Dateien kann beispielsweise ein Wi-Fi-Netzwerk anfordern, auch wenn mobile Daten aktiv sind. Dazu wird ein NetworkRequest mit addTransportType(TRANSPORT_WIFI) erstellt, und wenn Wi-Fi verfügbar ist, ruft das System onAvailable() auf. Die Anwendung bindet Sockets über network.bindSocket() oder OkHttp mit einem konfigurierten Network-Objekt an dieses Netzwerk. Dies bietet flexible Kontrolle über die Nutzung von Netzwerkschnittstellen.

Implementierungsbeispiel in Kotlin

Betrachten wir ein vollständiges Beispiel der Verwendung von ConnectivityManager mit der modernen API (NetworkCallback) in Clean Architecture. NetworkMonitor ist eine Wrapper-Klasse um ConnectivityManager, die den Netzwerkstatus reaktiv über StateFlow bereitstellt. Das ViewModel abonniert diesen Flow und leitet den Status an die UI weiter. Das Repository verwendet NetworkMonitor, um Entscheidungen über Netzwerkanfragen zu treffen. Dieser Ansatz gewährleistet Testbarkeit und Isolation von Plattformabhängigkeiten.

Das folgende Beispiel zeigt, wie ConnectivityManager mit registerDefaultNetworkCallback korrekt verwendet wird. Die Klasse NetworkMonitor kapselt die Arbeit mit dem Systemdienst und stellt einen sauberen Kotlin Flow bereit. Sie registriert den Callback beim Start und hebt ihn am Ende des Lebenszyklus auf. Asynchroner Betrieb wird durch Koroutinen und callbackFlow gewährleistet — eine Brücke zwischen dem Callback-Stil von ConnectivityManager und dem reaktiven Flow-Stil von 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
        )
    }
}

Verwendung von NetworkMonitor in ViewModel und Repository

Das ViewModel abonniert NetworkMonitor.isOnline über stateIn() und leitet den Status an Compose weiter. Das Repository prüft den aktuellen isOnline.value vor dem API-Aufruf: bei false — gibt es einen Flow aus Room zurück. Bei true — ruft es die API auf, speichert das Ergebnis in Room und gibt einen Flow aus Room zurück. WorkManager verwendet NetworkType.CONNECTED, um Hintergrundaufgaben einzuschränken. Das Testen von NetworkMonitor erfolgt mit einem Mock-Objekt von ConnectivityManager und einem gefälschten NetworkCallback, wodurch jedes Netzwerkszenario in Unit-Tests emuliert werden kann.

Best Practices und häufige Fehler

Die erste Regel bei der Arbeit mit ConnectivityManager ist, keine veraltete API zu verwenden. getActiveNetworkInfo() ist seit API 29 veraltet und kann auf neueren Android-Versionen falsche Daten zurückgeben. Verwenden Sie stattdessen getActiveNetwork() + getNetworkCapabilities() für einmalige Überprüfungen und registerDefaultNetworkCallback() für kontinuierliche Überwachung. Die alte Methode unterscheidet auch nicht zwischen Netzwerken mit Captive Portal und vollem Internetzugang, was zu Fehlalarmen führt.

Die zweite Regel ist, den Callback immer abzumelden. Wenn eine Activity einen NetworkCallback in onStart() registriert, aber nicht in onStop() abmeldet, läuft der Callback nach der Zerstörung der Activity weiter. Dies verursacht Speicherlecks und potenzielle NullPointerException, wenn der Callback versucht, die UI einer zerstörten Komponente zu aktualisieren. Verwenden Sie lifecycleScope oder repeatOnLifecycle für die automatische Registrierungsverwaltung. Verwenden Sie in Jetpack Compose DisposableEffect zum Registrieren und Abmelden des Callbacks.

Der dritte häufige Fehler ist die Überprüfung nur der Netzwerkverfügbarkeit ohne Berücksichtigung der Qualität. Ein einfaches „Gibt es Internet?“ reicht für Entscheidungen nicht aus. Die Anwendung sollte NET_CAPABILITY_NOT_METERED für große Downloads, NET_CAPABILITY_NOT_ROAMING für Hintergrundsynchronisation und NET_CAPABILITY_VALIDATED zur Bestätigung des Internetzugangs prüfen. Das Ignorieren dieser Flags führt dazu, dass die Anwendung versucht, Videos im Roaming herunterzuladen oder Daten über ein Hotel-Captive-Portal zu synchronisieren.

Die vierte Regel ist, ConnectivityManager nicht zur Überprüfung der Verfügbarkeit eines bestimmten Servers zu verwenden. ConnectivityManager meldet den Netzwerkstatus auf dem Gerät, garantiert aber nicht, dass der Server erreichbar ist. Verwenden Sie für die Überprüfung der API-Verfügbarkeit eine HTTP-Anfrage mit kurzem Timeout oder einen Health Check. ConnectivityManager + HTTP-Ping ist eine zuverlässige Kombination: Zuerst die Netzwerkverfügbarkeit prüfen, dann eine leichte Anfrage an den Server senden, um die tatsächliche Erreichbarkeit zu bestätigen.

Testen von ConnectivityManager

Verwenden Sie für Unit-Tests Robolectric mit ShadowConnectivityManager, der Netzwerkzustände emulieren kann. Für Integrationstests — Android Test Orchestrator mit Flugmodus-Umschaltung. Testen Sie Szenarien: Übergang von Online zu Offline, Auftreten von Wi-Fi bei aktiven mobilen Daten, Netzwerkverlust während einer Anfrage, Captive Portal, Roaming. Verwenden Sie für Mocking in Unit-Tests eine Wrapper-Schnittstelle (z. B. NetworkMonitorInterface), die ohne Plattformabhängigkeiten durch ein Mock-Objekt ersetzt werden kann.