Connectivity Manager: qué es, métodos y monitoreo de conexión

¿Qué es Connectivity Manager?

ConnectivityManager es un servicio del sistema operativo Android, accesible a través de Context.getSystemService(Context.CONNECTIVITY_SERVICE). Proporciona una API para obtener información sobre la conexión de red del dispositivo, monitorear cambios de red y gestionar las solicitudes de red de la aplicación. Connectivity Manager ha sido parte de Android Framework desde la primera versión de la plataforma (API Level 1) y ha experimentado cambios significativos a lo largo de las décadas: desde el simple getActiveNetworkInfo() hasta el moderno modelo reactivo con NetworkCallback y NetworkRequest.

Las principales capacidades de Connectivity Manager incluyen: verificar la presencia de una conexión de red activa, determinar el tipo de red (Wi-Fi, datos móviles, Ethernet, Bluetooth, VPN), monitorear cambios en el estado de la red en tiempo real, obtener información sobre el ancho de banda y la latencia, y gestionar las solicitudes de red de la aplicación. ConnectivityManager se utiliza junto con WorkManager y Repository para implementar arquitectura Offline-First, carga adaptativa de contenido y optimización de la aplicación según la calidad de la conexión.

A partir de Android 10 (API 29), Google cambió el enfoque para trabajar con ConnectivityManager. El método getActiveNetworkInfo() está declarado obsoleto, y en su lugar se recomienda usar registerDefaultNetworkCallback() o registerNetworkCallback() con NetworkRequest. La nueva API proporciona información de red más detallada, incluida la capacidad de detectar portales cautivos (Wi-Fi con autenticación) y evaluar la calidad de la conexión. ConnectivityManager también está integrado con la familia Jetpack: la biblioteca ConnectivityManager se lanzó en 2024 como parte de Jetpack para simplificar el monitoreo de red en aplicaciones Compose.

El papel de Connectivity Manager en la arquitectura de la aplicación

En la arquitectura moderna de Android, Connectivity Manager se utiliza a nivel de repositorio o UseCase para tomar decisiones sobre solicitudes de red. La capa de Repositorio verifica el estado de la red antes de llamar a la API: si la red no está disponible, se devuelven datos del almacenamiento local (Room). Si la red está disponible, se realiza una solicitud al servidor y el resultado se guarda en Room. El ViewModel se suscribe a un Flow desde Room y no conoce los detalles de la interacción de red — esto permite probar cada capa de forma independiente.

Cómo funciona Connectivity Manager

Connectivity Manager obtiene información del estado de la red del servicio del sistema connectivity, que interactúa con las interfaces de red del kernel de Linux. Cuando el dispositivo se conecta a Wi-Fi o activa los datos móviles, el kernel notifica al servicio del sistema, que actualiza su estado interno y notifica a todos los callbacks registrados. La arquitectura de ConnectivityManager se basa en el patrón Observer: la aplicación registra un NetworkCallback y recibe notificaciones sobre cualquier cambio en la red — establecimiento de conexión, pérdida de conexión, cambio de tipo de red o degradación de la calidad.

La API moderna de ConnectivityManager utiliza NetworkRequest para filtrar eventos de red. NetworkRequest permite especificar requisitos para la red: transporte (Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET), capacidad de internet (NetworkCapabilities.NET_CAPABILITY_INTERNET) y otros criterios. Si una aplicación solo necesita Wi-Fi para descargar archivos grandes, crea un NetworkRequest con Transport.WIFI y registra un callback. El sistema notificará a la aplicación solo cuando cambie la conexión Wi-Fi, ignorando los eventos de la red móvil.

Una característica importante de Connectivity Manager en Android 12+ es la red basada en capacidades. La aplicación no solo verifica “¿hay internet?”, sino que puede evaluar qué tipo de tráfico está disponible. Por ejemplo, NET_CAPABILITY_NOT_METERED indica una conexión ilimitada (Wi-Fi), NET_CAPABILITY_NOT_ROAMING indica que el dispositivo no está en roaming. Esto permite tomar decisiones: descargar video solo por Wi-Fi, posponer la sincronización en roaming, o usar datos móviles solo para solicitudes críticas.

Permisos para Connectivity Manager

Para usar Connectivity Manager en una aplicación Android se requieren permisos. ACCESS_NETWORK_STATE es un permiso obligatorio para leer información de la red, declarado en AndroidManifest.xml. Sin este permiso, ConnectivityManager devolverá null para getActiveNetwork() y no invocará callbacks. Para realizar operaciones de red, también se requiere el permiso INTERNET. A partir de Android 10 (API 29), la aplicación puede verificar el estado de la red sin permisos adicionales en tiempo de ejecución — ACCESS_NETWORK_STATE es un permiso normal y se concede automáticamente durante la instalación.

Métodos principales de Connectivity Manager

El Connectivity Manager moderno proporciona varios métodos clave para trabajar con la red. getActiveNetwork() (API 23+) devuelve el objeto Network de la red activa actual o null si el dispositivo no está conectado. Este método no requiere callbacks y es adecuado para verificaciones únicas. El objeto Network se puede pasar a NetworkCapabilities para obtener información detallada: tipo de transporte, estado medido, roaming, capacidad de internet y otras características.

registerDefaultNetworkCallback() (API 24+) es la forma preferida de monitorear la red. La aplicación registra un callback que se invoca ante cualquier cambio en la red predeterminada (la red a través de la cual la aplicación envía tráfico). El callback recibe un objeto Network que se puede usar para vincular sockets y clientes HTTP. Este método reemplaza al obsoleto getActiveNetworkInfo() y proporciona monitoreo reactivo de la red sin polling.

registerNetworkCallback() (API 21+) permite suscribirse a cambios de un tipo de red específico a través de NetworkRequest. Por ejemplo, una aplicación puede rastrear solo redes Wi-Fi usando new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build(). El sistema notificará a la aplicación sobre la conexión/desconexión de Wi-Fi sin afectar los eventos de la red móvil. NetworkCapabilities.getLinkDownstreamBandwidthKbps() devuelve una estimación del ancho de banda descendente en kbit/s, lo que permite adaptar la calidad del contenido a la velocidad de la conexión.

ConnectivityManager en Jetpack Compose

La biblioteca Jetpack Connectivity (androidx.core:core-ktx) proporciona extensiones convenientes para trabajar con ConnectivityManager en Compose. La función ConnectivityManager.observeAsState() devuelve un State que se actualiza cuando cambia la red. El componente @Composable NetworkStatus() muestra el estado de la conexión y se redibuja automáticamente ante cambios. Esto libera al desarrollador de gestionar manualmente los callbacks y el ciclo de vida de Activity/Fragment.

NetworkCallback y manejo de cambios de red

ConnectivityManager.NetworkCallback es una clase abstracta con métodos que el sistema invoca cuando cambia el estado de la red. onAvailable(Network) se llama cuando una red está disponible. La aplicación recibe un objeto Network que se puede usar para vincular sockets mediante Network.bindSocket(). onLost(Network) se llama cuando una red deja de estar disponible. La aplicación debe cambiar a datos locales o mostrar un mensaje de falta de conexión. onCapabilitiesChanged(Network, NetworkCapabilities) se llama cuando cambian las características de la red (por ejemplo, al cambiar de Wi-Fi a datos móviles).

El manejo adecuado de los cambios de red requiere considerar el ciclo de vida del componente. El callback debe registrarse en onStart()/onResume() y cancelarse en onStop()/onPause(). Si el callback no se cancela, puede seguir ejecutándose después de que la Activity sea destruida, causando fugas de memoria y posibles NullPointerException cuando el callback intente actualizar la UI de un componente destruido. Use lifecycleScope o repeatOnLifecycle para la gestión automática del registro. En Jetpack Compose, use DisposableEffect para registrar y cancelar el callback.

Manejo de portales cautivos es una característica importante de ConnectivityManager a partir de Android 10. CAPTIVE_PORTAL es un escenario donde una red Wi-Fi está disponible pero requiere autenticación a través de una página web (aeropuertos, hoteles, cafeterías). NetworkCapabilities.NET_CAPABILITY_VALIDATED indica que la red tiene acceso completo a internet. Si NET_CAPABILITY_VALIDATED está ausente, la aplicación puede abrir un navegador para la autenticación del portal cautivo. El método isCaptivePortal(), agregado en Android 11 (API 30), se utiliza para detectar portales cautivos.

Red para propósitos específicos (NetworkRequest)

ConnectivityManager permite solicitar una red para propósitos específicos a través de requestNetwork() y bindProcessToNetwork(). Por ejemplo, una aplicación para descargar archivos grandes puede solicitar una red Wi-Fi incluso si los datos móviles están activos. Para ello, se crea un NetworkRequest con addTransportType(TRANSPORT_WIFI), y cuando Wi-Fi esté disponible, el sistema llama a onAvailable(). La aplicación vincula los sockets a esta red mediante network.bindSocket() u OkHttp con un objeto Network configurado. Esto proporciona un control flexible sobre el uso de las interfaces de red.

Ejemplo de implementación en Kotlin

Veamos un ejemplo completo del uso de ConnectivityManager con la API moderna (NetworkCallback) en Clean Architecture. NetworkMonitor es una clase envoltorio alrededor de ConnectivityManager que proporciona el estado de la red de forma reactiva a través de StateFlow. El ViewModel se suscribe a este Flow y pasa el estado a la UI. El Repository usa NetworkMonitor para tomar decisiones sobre las solicitudes de red. Este enfoque asegura la capacidad de prueba y el aislamiento de las dependencias de la plataforma.

El siguiente ejemplo muestra cómo usar correctamente ConnectivityManager con registerDefaultNetworkCallback. La clase NetworkMonitor encapsula el trabajo con el servicio del sistema y proporciona un Kotlin Flow limpio. Registra el callback al inicio y lo cancela al final del ciclo de vida. La operación asincrónica se garantiza mediante corutinas y callbackFlow — un puente entre el estilo de callbacks de ConnectivityManager y el estilo reactivo 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
        )
    }
}

Uso de NetworkMonitor en ViewModel y Repository

El ViewModel se suscribe a NetworkMonitor.isOnline mediante stateIn() y pasa el estado a Compose. El Repository verifica el valor actual de isOnline.value antes de llamar a la API: si es false — devuelve un Flow desde Room. Si es true — llama a la API, guarda el resultado en Room y devuelve un Flow desde Room. WorkManager usa NetworkType.CONNECTED para restringir las tareas en segundo plano. Las pruebas de NetworkMonitor se realizan con un objeto mock de ConnectivityManager y un NetworkCallback falso, lo que permite emular cualquier escenario de red en pruebas unitarias.

Mejores prácticas y errores comunes

La primera regla al trabajar con ConnectivityManager es no usar la API obsoleta. getActiveNetworkInfo() está obsoleto desde API 29 y puede devolver datos incorrectos en versiones nuevas de Android. En su lugar, use getActiveNetwork() + getNetworkCapabilities() para verificaciones únicas y registerDefaultNetworkCallback() para monitoreo continuo. El método antiguo tampoco distingue entre redes con portal cautivo e internet completo, lo que genera falsos positivos.

La segunda regla es siempre cancelar el registro del callback. Si una Activity registra un NetworkCallback en onStart() pero no lo cancela en onStop(), el callback continúa ejecutándose después de que la Activity sea destruida. Esto causa fugas de memoria y posibles NullPointerException cuando el callback intenta actualizar la UI de un componente destruido. Use lifecycleScope o repeatOnLifecycle para la gestión automática del registro. En Jetpack Compose, use DisposableEffect para registrar y cancelar el callback.

El tercer error común es verificar solo la disponibilidad de la red sin considerar su calidad. Un simple “¿hay internet?” no es suficiente para tomar decisiones. La aplicación debe verificar NET_CAPABILITY_NOT_METERED para descargar archivos grandes, NET_CAPABILITY_NOT_ROAMING para sincronización en segundo plano, y NET_CAPABILITY_VALIDATED para confirmar el acceso a internet. Ignorar estas banderas lleva a que la aplicación intente descargar video en roaming o sincronizar datos a través de un portal cautivo de hotel.

La cuarta regla es no usar ConnectivityManager para verificar la disponibilidad de un servidor específico. ConnectivityManager informa sobre el estado de la red en el dispositivo, pero no garantiza que el servidor sea accesible. Para verificar la disponibilidad de una API, use una solicitud HTTP con tiempo de espera corto o un Health Check. ConnectivityManager + ping HTTP es una combinación confiable: primero verifique la presencia de red, luego realice una solicitud ligera al servidor para confirmar la accesibilidad real.

Pruebas de ConnectivityManager

Para pruebas unitarias, use Robolectric con ShadowConnectivityManager, que permite emular estados de red. Para pruebas de integración — Android Test Orchestrator con cambio de modo Avión. En las pruebas, verifique escenarios: transición de en línea a fuera de línea, aparición de Wi-Fi con datos móviles activos, pérdida de red durante una solicitud, portal cautivo, roaming. Para mocking en pruebas unitarias, use una interfaz envoltorio (por ejemplo, NetworkMonitorInterface) que pueda reemplazarse con un objeto mock sin dependencias de plataforma.