Connectivity Manager : ce que c’est, méthodes et surveillance de la connexion

Qu’est-ce que Connectivity Manager ?

ConnectivityManager est un service système du système d’exploitation Android, accessible via Context.getSystemService(Context.CONNECTIVITY_SERVICE). Il fournit une API pour obtenir des informations sur la connexion réseau de l’appareil, surveiller les changements de réseau et gérer les requêtes réseau de l’application. Connectivity Manager fait partie d’Android Framework depuis la première version de la plateforme (API Level 1) et a subi des changements significatifs au fil des décennies : du simple getActiveNetworkInfo() au modèle réactif moderne avec NetworkCallback et NetworkRequest.

Les principales capacités de Connectivity Manager incluent : vérifier la présence d’une connexion réseau active, déterminer le type de réseau (Wi-Fi, données mobiles, Ethernet, Bluetooth, VPN), surveiller les changements d’état du réseau en temps réel, obtenir des informations sur la bande passante et la latence, et gérer les requêtes réseau de l’application. ConnectivityManager est utilisé avec WorkManager et Repository pour implémenter une architecture Offline-First, un chargement adaptatif de contenu et une optimisation de l’application en fonction de la qualité de la connexion.

À partir d’Android 10 (API 29), Google a modifié l’approche de travail avec ConnectivityManager. La méthode getActiveNetworkInfo() est déclarée obsolète, et il est recommandé d’utiliser à la place registerDefaultNetworkCallback() ou registerNetworkCallback() avec NetworkRequest. La nouvelle API fournit des informations réseau plus détaillées, y compris la capacité de détecter les portails captifs (Wi-Fi avec authentification) et d’évaluer la qualité de la connexion. ConnectivityManager est également intégré à la famille Jetpack : la bibliothèque ConnectivityManager a été publiée en 2024 dans le cadre de Jetpack pour simplifier la surveillance réseau dans les applications Compose.

Le rôle de Connectivity Manager dans l’architecture de l’application

Dans l’architecture Android moderne, Connectivity Manager est utilisé au niveau du référentiel ou de UseCase pour prendre des décisions sur les requêtes réseau. La couche de Référentiel vérifie l’état du réseau avant d’appeler l’API : si le réseau est indisponible, les données sont renvoyées depuis le stockage local (Room). Si le réseau est disponible, une requête au serveur est effectuée et le résultat est sauvegardé dans Room. Le ViewModel s’abonne à un Flow depuis Room et ne connaît pas les détails de l’interaction réseau — cela permet de tester chaque couche de manière indépendante.

Comment fonctionne Connectivity Manager

Connectivity Manager obtient les informations sur l’état du réseau à partir du service système connectivity, qui interagit avec les interfaces réseau du noyau Linux. Lorsque l’appareil se connecte au Wi-Fi ou active les données mobiles, le noyau notifie le service système, qui met à jour son état interne et notifie tous les callbacks enregistrés. L’architecture de ConnectivityManager est basée sur le modèle Observer : l’application enregistre un NetworkCallback et reçoit des notifications sur tout changement de réseau — établissement de connexion, perte de connexion, changement de type de réseau ou dégradation de la qualité.

L’API moderne de ConnectivityManager utilise NetworkRequest pour filtrer les événements réseau. NetworkRequest permet de spécifier des exigences pour le réseau : transport (Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET), capacité Internet (NetworkCapabilities.NET_CAPABILITY_INTERNET) et d’autres critères. Si une application a besoin uniquement de Wi-Fi pour télécharger des fichiers volumineux, elle crée un NetworkRequest avec Transport.WIFI et enregistre un callback. Le système notifiera l’application uniquement lorsque la connexion Wi-Fi change, en ignorant les événements du réseau mobile.

Une fonctionnalité importante de Connectivity Manager sur Android 12+ est le réseau basé sur les capacités. L’application ne vérifie pas simplement «y a-t-il Internet ?», mais peut évaluer quel type de trafic est disponible. Par exemple, NET_CAPABILITY_NOT_METERED indique une connexion illimitée (Wi-Fi), NET_CAPABILITY_NOT_ROAMING indique que l’appareil n’est pas en itinérance. Cela permet de prendre des décisions : télécharger une vidéo uniquement en Wi-Fi, reporter la synchronisation en itinérance, ou utiliser les données mobiles uniquement pour les requêtes critiques.

Autorisations pour Connectivity Manager

Pour utiliser Connectivity Manager dans une application Android, des autorisations sont nécessaires. ACCESS_NETWORK_STATE est une autorisation obligatoire pour lire les informations réseau, déclarée dans AndroidManifest.xml. Sans cette autorisation, ConnectivityManager renverra null pour getActiveNetwork() et n’invoquera pas les callbacks. Pour effectuer des opérations réseau, l’autorisation INTERNET est également nécessaire. À partir d’Android 10 (API 29), l’application peut vérifier l’état du réseau sans autorisations supplémentaires au moment de l’exécution — ACCESS_NETWORK_STATE est une autorisation normale et est accordée automatiquement lors de l’installation.

Méthodes principales de Connectivity Manager

Le Connectivity Manager moderne fournit plusieurs méthodes clés pour travailler avec le réseau. getActiveNetwork() (API 23+) renvoie l’objet Network du réseau actif actuel ou null si l’appareil n’est pas connecté. Cette méthode ne nécessite pas de callbacks et convient pour les vérifications ponctuelles. L’objet Network peut être transmis à NetworkCapabilities pour obtenir des informations détaillées : type de transport, statut de comptage, itinérance, capacité Internet et autres caractéristiques.

registerDefaultNetworkCallback() (API 24+) est la méthode préférée pour surveiller le réseau. L’application enregistre un callback qui est invoqué lors de tout changement du réseau par défaut (le réseau par lequel l’application envoie le trafic). Le callback reçoit un objet Network qui peut être utilisé pour lier des sockets et des clients HTTP. Cette méthode remplace l’obsolète getActiveNetworkInfo() et fournit une surveillance réactive du réseau sans sondage.

registerNetworkCallback() (API 21+) permet de s’abonner aux changements d’un type de réseau spécifique via NetworkRequest. Par exemple, une application peut suivre uniquement les réseaux Wi-Fi en utilisant new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build(). Le système notifiera l’application de la connexion/déconnexion Wi-Fi sans affecter les événements du réseau mobile. NetworkCapabilities.getLinkDownstreamBandwidthKbps() renvoie une estimation de la bande passante descendante en kbit/s, permettant d’adapter la qualité du contenu à la vitesse de la connexion.

ConnectivityManager dans Jetpack Compose

La bibliothèque Jetpack Connectivity (androidx.core:core-ktx) fournit des extensions pratiques pour travailler avec ConnectivityManager dans Compose. La fonction ConnectivityManager.observeAsState() renvoie un State qui se met à jour lorsque le réseau change. Le composant @Composable NetworkStatus() affiche l’état de la connexion et se redessine automatiquement lors des changements. Cela évite au développeur de gérer manuellement les callbacks et le cycle de vie Activity/Fragment.

NetworkCallback et gestion des changements de réseau

ConnectivityManager.NetworkCallback est une classe abstraite avec des méthodes appelées par le système lorsque l’état du réseau change. onAvailable(Network) est appelé lorsqu’un réseau devient disponible. L’application reçoit un objet Network qui peut être utilisé pour lier des sockets via Network.bindSocket(). onLost(Network) est appelé lorsqu’un réseau devient indisponible. L’application doit basculer vers les données locales ou afficher un message d’absence de connexion. onCapabilitiesChanged(Network, NetworkCapabilities) est appelé lorsque les caractéristiques du réseau changent (par exemple, lors du passage du Wi-Fi aux données mobiles).

La gestion correcte des changements de réseau nécessite de prendre en compte le cycle de vie du composant. Le callback doit être enregistré dans onStart()/onResume() et annulé dans onStop()/onPause(). Si le callback n’est pas annulé, il peut continuer à s’exécuter après la destruction de l’Activity, provoquant des fuites mémoire et des NullPointerException potentiels lorsque le callback tente de mettre à jour l’interface d’un composant détruit. Utilisez lifecycleScope ou repeatOnLifecycle pour la gestion automatique de l’enregistrement. Dans Jetpack Compose, utilisez DisposableEffect pour enregistrer et annuler le callback.

Gestion des portails captifs est une fonctionnalité importante de ConnectivityManager à partir d’Android 10. CAPTIVE_PORTAL est un scénario où un réseau Wi-Fi est disponible mais nécessite une authentification via une page web (aéroports, hôtels, cafés). NetworkCapabilities.NET_CAPABILITY_VALIDATED indique que le réseau a un accès complet à Internet. Si NET_CAPABILITY_VALIDATED est absent, l’application peut ouvrir un navigateur pour l’authentification du portail captif. La méthode isCaptivePortal(), ajoutée dans Android 11 (API 30), est utilisée pour détecter les portails captifs.

Réseau pour des fins spécifiques (NetworkRequest)

ConnectivityManager permet de demander un réseau à des fins spécifiques via requestNetwork() et bindProcessToNetwork(). Par exemple, une application de téléchargement de fichiers volumineux peut demander un réseau Wi-Fi même si les données mobiles sont actives. Pour cela, un NetworkRequest est créé avec addTransportType(TRANSPORT_WIFI), et lorsque le Wi-Fi est disponible, le système appelle onAvailable(). L’application lie les sockets à ce réseau via network.bindSocket() ou OkHttp avec un objet Network configuré. Cela offre un contrôle flexible sur l’utilisation des interfaces réseau.

Exemple d’implémentation en Kotlin

Examinons un exemple complet d’utilisation de ConnectivityManager avec l’API moderne (NetworkCallback) dans Clean Architecture. NetworkMonitor est une classe wrapper autour de ConnectivityManager qui fournit l’état du réseau de manière réactive via StateFlow. Le ViewModel s’abonne à ce Flow et transmet l’état à l’interface utilisateur. Le Repository utilise NetworkMonitor pour prendre des décisions sur les requêtes réseau. Cette approche garantit la testabilité et l’isolation des dépendances de la plateforme.

L’exemple ci-dessous montre comment utiliser correctement ConnectivityManager avec registerDefaultNetworkCallback. La classe NetworkMonitor encapsule le travail avec le service système et fournit un Kotlin Flow propre. Elle enregistre le callback au démarrage et l’annule à la fin du cycle de vie. Le fonctionnement asynchrone est assuré par les coroutines et callbackFlow — un pont entre le style de callbacks de ConnectivityManager et le style réactif Flow de 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
        )
    }
}

Utilisation de NetworkMonitor dans ViewModel et Repository

Le ViewModel s’abonne à NetworkMonitor.isOnline via stateIn() et transmet l’état à Compose. Le Repository vérifie la valeur actuelle de isOnline.value avant d’appeler l’API : si false — renvoie un Flow depuis Room. Si true — appelle l’API, sauvegarde le résultat dans Room et renvoie un Flow depuis Room. WorkManager utilise NetworkType.CONNECTED pour contraindre les tâches en arrière-plan. Le test de NetworkMonitor se fait avec un objet mock de ConnectivityManager et un faux NetworkCallback, permettant d’émuler tout scénario réseau dans les tests unitaires.

Bonnes pratiques et erreurs courantes

La première règle de travail avec ConnectivityManager est de ne pas utiliser l’API obsolète. getActiveNetworkInfo() est obsolète depuis API 29 et peut renvoyer des données incorrectes sur les nouvelles versions d’Android. Utilisez plutôt getActiveNetwork() + getNetworkCapabilities() pour les vérifications ponctuelles et registerDefaultNetworkCallback() pour une surveillance continue. L’ancienne méthode ne distingue pas non plus les réseaux avec portail captif de ceux avec accès Internet complet, ce qui entraîne des faux positifs.

La deuxième règle est de toujours annuler l’enregistrement du callback. Si une Activity enregistre un NetworkCallback dans onStart() mais ne l’annule pas dans onStop(), le callback continue de s’exécuter après la destruction de l’Activity. Cela provoque des fuites mémoire et des NullPointerException potentiels lorsque le callback tente de mettre à jour l’interface d’un composant détruit. Utilisez lifecycleScope ou repeatOnLifecycle pour la gestion automatique de l’enregistrement. Dans Jetpack Compose, utilisez DisposableEffect pour enregistrer et annuler le callback.

La troisième erreur courante est de vérifier uniquement la disponibilité du réseau sans tenir compte de sa qualité. Un simple «y a-t-il Internet ?» ne suffit pas pour prendre des décisions. L’application doit vérifier NET_CAPABILITY_NOT_METERED pour le téléchargement de fichiers volumineux, NET_CAPABILITY_NOT_ROAMING pour la synchronisation en arrière-plan, et NET_CAPABILITY_VALIDATED pour confirmer l’accès à Internet. Ignorer ces indicateurs conduit l’application à tenter de télécharger une vidéo en itinérance ou de synchroniser des données via un portail captif d’hôtel.

La quatrième règle est de ne pas utiliser ConnectivityManager pour vérifier la disponibilité d’un serveur spécifique. ConnectivityManager indique l’état du réseau sur l’appareil, mais ne garantit pas que le serveur soit accessible. Pour vérifier la disponibilité d’une API, utilisez une requête HTTP avec un délai d’attente court ou un Health Check. ConnectivityManager + ping HTTP est une combinaison fiable : vérifiez d’abord la présence du réseau, puis effectuez une requête légère au serveur pour confirmer l’accessibilité réelle.

Test de ConnectivityManager

Pour les tests unitaires, utilisez Robolectric avec ShadowConnectivityManager, qui permet d’émuler les états du réseau. Pour les tests d’intégration — Android Test Orchestrator avec basculement du mode Avion. Dans les tests, vérifiez les scénarios : transition de la connexion à la déconnexion, apparition du Wi-Fi avec données mobiles actives, perte du réseau pendant une requête, portail captif, itinérance. Pour le mocking dans les tests unitaires, utilisez une interface wrapper (par exemple, NetworkMonitorInterface) qui peut être remplacée par un objet mock sans dépendances de plateforme.