NetworkCallback: o que é, aplicação e tratamento de rede no Android

O que é NetworkCallback?

NetworkCallback é uma classe abstrata do pacote android.net, que faz parte do Android SDK. Ela foi projetada para receber notificações sobre mudanças no estado da conexão de rede através do serviço de sistema ConnectivityManager.

Antes do NetworkCallback, os desenvolvedores usavam BroadcastReceiver para rastrear mudanças de rede. Essa abordagem exigia registro constante no manifesto, funcionava com atrasos e não fornecia informações detalhadas sobre as características da conexão. Android 5.0 (API 21) introduziu o NetworkCallback como uma alternativa mais flexível e eficiente.

O callback funciona de forma assíncrona: o aplicativo se inscreve em eventos através do ConnectivityManager, e o sistema chama os métodos do callback quando o estado da rede muda. Isso elimina a necessidade de consultas periódicas do status da rede, economizando recursos de bateria e CPU.

Como o callback funciona no Android

O ConnectivityManager gerencia todas as interfaces de rede do dispositivo — Wi-Fi, dados móveis, Ethernet, VPN. Quando qualquer uma dessas interfaces muda, o sistema cria um objeto Network e o passa para o método correspondente do callback registrado. Cada Network tem um identificador único que muda na reconexão.

O callback não está vinculado a um tipo específico de rede — ele pode rastrear todas as interfaces disponíveis simultaneamente. Para filtrar os tipos de conexão, usa-se a classe NetworkRequest, que especifica os protocolos de transporte necessários (Wi-Fi, dados celulares, Ethernet) e as capacidades da rede.

Como Registrar NetworkCallback no seu Aplicativo

O registro do NetworkCallback é feito através do método ConnectivityManager.registerNetworkCallback. O primeiro parâmetro é um NetworkRequest.Builder que descreve os requisitos de rede, o segundo é uma instância do callback. A permissão ACCESS_NETWORK_STATE é necessária no manifesto.

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 em Activity e Fragment

Recomenda-se registrar o NetworkCallback quando o aplicativo está em primeiro plano e cancelá-lo ao ir para segundo plano. Em Activity, use onStart e onStop para gerenciar o ciclo de vida do callback. Em Fragment, use onResume e onPause.

Para simplificar o gerenciamento do registro, você pode usar componentes Lifecycle-aware. A biblioteca AndroidX Lifecycle permite criar um LifecycleObserver personalizado que registra e cancela automaticamente o callback quando o estado do ciclo de vida muda.

Registro em um Service

Para tarefas em segundo plano, o registro é feito em um Service ou WorkManager. Observe que no Android 8+, os serviços em segundo plano têm restrições de inicialização. WorkManager com NetworkType é uma maneira mais confiável de executar tarefas sob um estado de rede específico, pois é integrado com a API de compatibilidade e respeita o modo Doze.

Principais Métodos do NetworkCallback

O NetworkCallback fornece um conjunto de métodos que são chamados quando o estado da rede muda. Nem todos os métodos precisam ser sobrescritos — implemente apenas aqueles necessários para a tarefa específica do seu aplicativo. onAvailable e onLost são o mínimo necessário para o monitoramento básico da conexão.

Método onCapabilitiesChanged

Este método é chave para obter informações detalhadas da rede. O parâmetro NetworkCapabilities contém flags: NET_CAPABILITY_INTERNET — acesso à internet disponível, NET_CAPABILITY_NOT_METERED — conexão ilimitada, NET_CAPABILITY_NOT_ROAMING — sem roaming. Também é possível saber a latência do sinal e a largura de banda.

Portais cativos são um caso especial: ao conectar-se a uma rede Wi-Fi pública através de um portal, o método onCapabilitiesChanged não mostra INTERNET imediatamente. A rede está disponível inicialmente, mas sem internet — é necessária autorização através do navegador. Os desenvolvedores precisam considerar esse atraso na lógica do aplicativo.

Método onBlockedStatusChanged

É chamado quando o sistema bloqueia o tráfego de rede para o aplicativo — por exemplo, quando o modo de economia de dados é ativado ou os dados em segundo plano são restritos. onBlockedStatusChanged permite que o aplicativo saiba que suas requisições de rede estão temporariamente proibidas e mude para o processamento local.

Exemplos de Implementação do NetworkCallback

Vamos ver uma implementação prática do NetworkCallback para monitorar o acesso à internet e lidar com portais cativos. O exemplo abaixo mostra a verificação de NET_CAPABILITY_INTERNET e a validação da conexão através de uma requisição HTTP ao servidor do 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}")
        // Parar requisições de rede
    }
}

Lidando com Portais Cativos

Ao conectar-se a uma rede pública com autorização (café, aeroporto), o sistema primeiro informa onAvailable, mas onCapabilitiesChanged pode não mostrar INTERNET. Nesses casos, é necessária uma verificação adicional através de uma requisição HTTP a um endpoint estável, como https://www.google.com/generate_204.

Se a requisição retornar o código 204 — a internet está disponível. Se houver um redirecionamento (301, 302, 307) — é necessária autorização através do navegador. Nesse caso, você pode abrir uma WebView ou Intent com a URL de redirecionamento para completar a autenticação no 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}")
        }
    }
}

Diferenças de Outros Métodos de Monitoramento de Rede

Antes do NetworkCallback, o método principal para monitorar a rede era o BroadcastReceiver com o filtro android.net.conn.CONNECTIVITY_CHANGE. Essa abordagem tinha desvantagens significativas: atrasos de vários segundos, falta de informações sobre o tipo de interface e maior consumo de energia devido ao despertar constante do dispositivo.

Uma alternativa moderna é LiveData ou StateFlow combinados com NetworkCallback. O padrão envolve encapsular o callback em um fluxo reativo que notifica automaticamente a UI sobre mudanças de estado. Por exemplo, um MutableStateFlow com tipo NetworkStatus é atualizado dentro dos métodos do callback, e um ViewCollector se inscreve nas mudanças.

Trabalhando em Modo Segundo Plano

A partir do Android 10, as restrições de segundo plano são mais rigorosas e o NetworkCallback pode não ser chamado quando o aplicativo está em segundo plano. Para tarefas críticas — como carregar dados quando a rede ficar disponível — use o WorkManager com a restrição NetworkType.CONNECTED. O WorkManager garante a execução da tarefa quando as condições de rede são atendidas.

No Android 12+, há uma restrição no registro no manifesto do BroadcastReceiver para CONNECTIVITY_ACTION. Os desenvolvedores devem migrar para o NetworkCallback ou usar o WorkManager. A política do Google Play desde agosto de 2022 exige a remoção do registro no manifesto para esta ação.