NetworkCallback: qué es, aplicación y manejo de red en Android

¿Qué es NetworkCallback?

NetworkCallback es una clase abstracta del paquete android.net, que forma parte del SDK de Android. Está diseñada para recibir notificaciones sobre cambios en el estado de la conexión de red a través del servicio del sistema ConnectivityManager.

Antes de NetworkCallback, los desarrolladores usaban BroadcastReceiver para rastrear los cambios de red. Este enfoque requería registro constante en el manifiesto, funcionaba con retrasos y no proporcionaba información detallada sobre las características de la conexión. Android 5.0 (API 21) introdujo NetworkCallback como una alternativa más flexible y eficiente.

El callback funciona de forma asíncrona: la aplicación se suscribe a eventos a través de ConnectivityManager, y el sistema llama a los métodos del callback cuando cambia el estado de la red. Esto elimina la necesidad de consultas periódicas del estado de la red, ahorrando recursos de batería y CPU.

Cómo funciona el callback en Android

ConnectivityManager gestiona todas las interfaces de red del dispositivo: Wi-Fi, datos móviles, Ethernet, VPN. Cuando cualquiera de estas interfaces cambia, el sistema crea un objeto Network y lo pasa al método correspondiente del callback registrado. Cada Network tiene un identificador único que cambia al reconectarse.

El callback no está vinculado a un tipo de red específico: puede rastrear todas las interfaces disponibles simultáneamente. Para filtrar los tipos de conexión, se usa la clase NetworkRequest, que especifica los protocolos de transporte requeridos (Wi-Fi, datos móviles, Ethernet) y las capacidades de la red.

Cómo Registrar NetworkCallback en tu Aplicación

El registro de NetworkCallback se realiza mediante el método ConnectivityManager.registerNetworkCallback. El primer parámetro es un NetworkRequest.Builder que describe los requisitos de red, el segundo es una instancia del callback. Se requiere el permiso ACCESS_NETWORK_STATE en el manifiesto.

class NetworkMonitor(private val context: Context) {

    private val connectivityManager =
        context.getSystemService(Context.CONNECTIVITY_SERVICE)
            as ConnectivityManager

    private val callback =
        object : ConnectivityManager.NetworkCallback() {

        override fun onAvailable(network: Network) {
            Log.d("Network", "Available: ${network}")
        }

        override fun onLost(network: Network) {
            Log.d("Network", "Lost: ${network}")
        }
    }

    fun register() {
        connectivityManager.registerNetworkCallback(
            NetworkRequest.Builder().build(), callback
        )
    }

    fun unregister() {
        connectivityManager.unregisterNetworkCallback(callback)
    }
}

Registro en Activity y Fragment

Se recomienda registrar NetworkCallback cuando la aplicación está en primer plano y cancelarlo al pasar a segundo plano. En Activity, usa onStart y onStop para gestionar el ciclo de vida del callback. En Fragment, usa onResume y onPause.

Para simplificar la gestión del registro, puedes usar componentes Lifecycle-aware. La biblioteca AndroidX Lifecycle permite crear un LifecycleObserver personalizado que registra y cancela automáticamente el callback cuando cambia el estado del ciclo de vida.

Registro en un Servicio

Para tareas en segundo plano, el registro se realiza en un Service o WorkManager. Ten en cuenta que en Android 8+, los servicios en segundo plano tienen restricciones de inicio. WorkManager con NetworkType es una forma más confiable de ejecutar tareas bajo un estado de red específico, ya que se integra con la API de compatibilidad y respeta el modo Doze.

Métodos Principales de NetworkCallback

NetworkCallback proporciona un conjunto de métodos que se llaman cuando cambia el estado de la red. No todos los métodos necesitan ser sobrescritos: implementa solo los que necesites para la tarea específica de tu aplicación. onAvailable y onLost son los mínimos necesarios para el monitoreo básico de la conexión.

Método onCapabilitiesChanged

Este método es clave para obtener información detallada de la red. El parámetro NetworkCapabilities contiene indicadores: NET_CAPABILITY_INTERNET — acceso a internet disponible, NET_CAPABILITY_NOT_METERED — conexión sin límite, NET_CAPABILITY_NOT_ROAMING — sin roaming. También se puede conocer la latencia de la señal y el ancho de banda.

Los portales cautivos son un caso especial: al conectarse a una red Wi-Fi pública a través de un portal, el método onCapabilitiesChanged no muestra INTERNET de inmediato. La red está disponible inicialmente pero sin internet — se requiere autorización mediante el navegador. Los desarrolladores deben tener en cuenta este retraso en la lógica de la aplicación.

Método onBlockedStatusChanged

Se llama cuando el sistema bloquea el tráfico de red para la aplicación — por ejemplo, cuando se activa el modo de ahorro de datos o se restringen los datos en segundo plano. onBlockedStatusChanged permite que la aplicación sepa que sus solicitudes de red están temporalmente prohibidas y cambie al procesamiento local.

Ejemplos de Implementación de NetworkCallback

Veamos una implementación práctica de NetworkCallback para monitorear el acceso a internet y manejar portales cautivos. El siguiente ejemplo muestra la verificación de NET_CAPABILITY_INTERNET y la validación de la conexión mediante una solicitud HTTP al servidor de Google.

val networkCallback = object : ConnectivityManager.NetworkCallback() {

    override fun onCapabilitiesChanged(
        network: Network,
        caps: NetworkCapabilities
    ) {
        val hasInternet = caps.hasCapability(
            NetworkCapabilities.NET_CAPABILITY_INTERNET
        )
        val isMetered = caps.hasCapability(
            NetworkCapabilities.NET_CAPABILITY_NOT_METERED
        ).not()

        when {
            hasInternet && isMetered ->
                Log.d("Network", "Mobile data connected")
            hasInternet ->
                Log.d("Network", "Wi-Fi connected")
            else ->
                Log.d("Network", "No internet access")
        }
    }

    override fun onLost(network: Network) {
        Log.d("Network", "Connection lost: ${network}")
        // Detener solicitudes de red
    }
}

Manejo de Portales Cautivos

Al conectarse a una red pública con autorización (café, aeropuerto), el sistema primero informa onAvailable, pero onCapabilitiesChanged puede no mostrar INTERNET. En tales casos, se requiere una verificación adicional mediante una solicitud HTTP a un endpoint estable, como https://www.google.com/generate_204.

Si la solicitud devuelve el código 204 — hay internet. Si hay una redirección (301, 302, 307) — se requiere autorización mediante navegador. En este caso, puedes abrir un WebView o Intent con la URL de redirección para completar la autenticación en el portal.

fun Context.validateInternet(network: Network) {
    CoroutineScope(Dispatchers.IO).launch {
        try {
            val url = URL("https://www.google.com/generate_204")
            val connection =
                network.openConnection(url) as HttpURLConnection
            connection.instanceFollowRedirects = false
            connection.connect()
            when (connection.responseCode) {
                HttpURLConnection.HTTP_NO_CONTENT ->
                    Log.d("Network", "Internet is available")
                in HttpURLConnection.HTTP_MOVED_PERM
                        ..HttpURLConnection.HTTP_TEMP_REDIRECT ->
                    Log.d("Network", "Captive portal detected")
            }
            connection.disconnect()
        } catch (e: Exception) {
            Log.e("Network", "Validation failed: ${e.message}")
        }
    }
}

Diferencias con Otros Métodos de Monitoreo de Red

Antes de NetworkCallback, el método principal para monitorear la red era BroadcastReceiver con el filtro android.net.conn.CONNECTIVITY_CHANGE. Este enfoque tenía inconvenientes significativos: retrasos de varios segundos, falta de información sobre el tipo de interfaz y mayor consumo de energía debido al constante despertar del dispositivo.

Una alternativa moderna es LiveData o StateFlow combinados con NetworkCallback. El patrón consiste en envolver el callback en un flujo reactivo que notifica automáticamente a la UI sobre los cambios de estado. Por ejemplo, un MutableStateFlow con tipo NetworkStatus se actualiza dentro de los métodos del callback, y un ViewCollector se suscribe a los cambios.

Manejo en Modo Segundo Plano

A partir de Android 10, las restricciones de segundo plano son más estrictas y es posible que NetworkCallback no se llame cuando la aplicación está en segundo plano. Para tareas críticas — como carga de datos cuando la red está disponible — usa WorkManager con la restricción NetworkType.CONNECTED. WorkManager garantiza la ejecución de la tarea cuando se cumplen las condiciones de red.

En Android 12+, hay una restricción en el registro en el manifiesto de BroadcastReceiver para CONNECTIVITY_ACTION. Los desarrolladores deben migrar a NetworkCallback o usar WorkManager. La política de Google Play desde agosto de 2022 exige la eliminación del registro en el manifiesto para esta acción.