Connectivity Manager: o que é, métodos e monitoramento de conexão

O que é Connectivity Manager?

ConnectivityManager é um serviço do sistema operacional Android, acessível através de Context.getSystemService(Context.CONNECTIVITY_SERVICE). Ele fornece uma API para obter informações sobre a conexão de rede do dispositivo, monitorar mudanças de rede e gerenciar as solicitações de rede do aplicativo. O Connectivity Manager faz parte do Android Framework desde a primeira versão da plataforma (API Level 1) e passou por mudanças significativas ao longo das décadas: desde o simples getActiveNetworkInfo() até o moderno modelo reativo com NetworkCallback e NetworkRequest.

As principais capacidades do Connectivity Manager incluem: verificar a presença de uma conexão de rede ativa, determinar o tipo de rede (Wi-Fi, dados móveis, Ethernet, Bluetooth, VPN), monitorar mudanças no estado da rede em tempo real, obter informações sobre largura de banda e latência, e gerenciar as solicitações de rede do aplicativo. ConnectivityManager é usado em conjunto com WorkManager e Repository para implementar arquitetura Offline-First, carregamento adaptativo de conteúdo e otimização do aplicativo com base na qualidade da conexão.

A partir do Android 10 (API 29), o Google mudou a abordagem para trabalhar com ConnectivityManager. O método getActiveNetworkInfo() foi declarado obsoleto, e em seu lugar é recomendado usar registerDefaultNetworkCallback() ou registerNetworkCallback() com NetworkRequest. A nova API fornece informações de rede mais detalhadas, incluindo a capacidade de detectar portais cativos (Wi-Fi com autenticação) e avaliar a qualidade da conexão. O ConnectivityManager também está integrado com a família Jetpack: a biblioteca ConnectivityManager foi lançada em 2024 como parte do Jetpack para simplificar o monitoramento de rede em aplicativos Compose.

O papel do Connectivity Manager na arquitetura do aplicativo

Na arquitetura moderna do Android, o Connectivity Manager é usado no nível do repositório ou UseCase para tomar decisões sobre solicitações de rede. A camada de Repositório verifica o estado da rede antes de chamar a API: se a rede estiver indisponível, os dados são retornados do armazenamento local (Room). Se a rede estiver disponível, uma solicitação ao servidor é feita e o resultado salvo no Room. O ViewModel se inscreve em um Flow do Room e não conhece os detalhes da interação de rede — isso permite testar cada camada de forma independente.

Como funciona o Connectivity Manager

O Connectivity Manager obtém informações do estado da rede do serviço do sistema connectivity, que interage com as interfaces de rede do kernel Linux. Quando o dispositivo se conecta ao Wi-Fi ou ativa os dados móveis, o kernel notifica o serviço do sistema, que atualiza seu estado interno e notifica todos os callbacks registrados. A arquitetura do ConnectivityManager é baseada no padrão Observer: o aplicativo registra um NetworkCallback e recebe notificações sobre quaisquer mudanças na rede — estabelecimento de conexão, perda de conexão, mudança de tipo de rede ou degradação de qualidade.

A API moderna do ConnectivityManager usa NetworkRequest para filtrar eventos de rede. O NetworkRequest permite especificar requisitos para a rede: transporte (Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET), capacidade de internet (NetworkCapabilities.NET_CAPABILITY_INTERNET) e outros critérios. Se um aplicativo precisar apenas de Wi-Fi para baixar arquivos grandes, ele cria um NetworkRequest com Transport.WIFI e registra um callback. O sistema notificará o aplicativo apenas quando a conexão Wi-Fi mudar, ignorando eventos da rede móvel.

Uma característica importante do Connectivity Manager no Android 12+ é a rede baseada em capacidades. O aplicativo não apenas verifica “tem internet?”, mas pode avaliar que tipo de tráfego está disponível. Por exemplo, NET_CAPABILITY_NOT_METERED indica uma conexão ilimitada (Wi-Fi), NET_CAPABILITY_NOT_ROAMING indica que o dispositivo não está em roaming. Isso permite tomar decisões: baixar vídeo apenas por Wi-Fi, adiar a sincronização em roaming, ou usar dados móveis apenas para solicitações críticas.

Permissões para Connectivity Manager

Para usar o Connectivity Manager em um aplicativo Android, são necessárias permissões. ACCESS_NETWORK_STATE é uma permissão obrigatória para ler informações de rede, declarada no AndroidManifest.xml. Sem esta permissão, o ConnectivityManager retornará null para getActiveNetwork() e não invocará callbacks. Para realizar operações de rede, a permissão INTERNET também é necessária. A partir do Android 10 (API 29), o aplicativo pode verificar o estado da rede sem permissões adicionais em tempo de execução — ACCESS_NETWORK_STATE é uma permissão normal e é concedida automaticamente durante a instalação.

Métodos principais do Connectivity Manager

O Connectivity Manager moderno fornece vários métodos principais para trabalhar com a rede. getActiveNetwork() (API 23+) retorna o objeto Network da rede ativa atual ou null se o dispositivo não estiver conectado. Este método não requer callbacks e é adequado para verificações únicas. O objeto Network pode ser passado para NetworkCapabilities para obter informações detalhadas: tipo de transporte, status medido, roaming, capacidade de internet e outras características.

registerDefaultNetworkCallback() (API 24+) é a maneira preferida de monitorar a rede. O aplicativo registra um callback que é invocado em quaisquer mudanças na rede padrão (a rede através da qual o aplicativo envia tráfego). O callback recebe um objeto Network que pode ser usado para vincular sockets e clientes HTTP. Este método substitui o obsoleto getActiveNetworkInfo() e fornece monitoramento reativo de rede sem polling.

registerNetworkCallback() (API 21+) permite inscrever-se em mudanças de um tipo de rede específico através de NetworkRequest. Por exemplo, um aplicativo pode rastrear apenas redes Wi-Fi usando new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build(). O sistema notificará o aplicativo sobre conexão/desconexão de Wi-Fi sem afetar os eventos da rede móvel. NetworkCapabilities.getLinkDownstreamBandwidthKbps() retorna uma estimativa da largura de banda downstream em kbit/s, permitindo adaptar a qualidade do conteúdo à velocidade da conexão.

ConnectivityManager no Jetpack Compose

A biblioteca Jetpack Connectivity (androidx.core:core-ktx) fornece extensões convenientes para trabalhar com ConnectivityManager no Compose. A função ConnectivityManager.observeAsState() retorna um State que é atualizado quando a rede muda. O componente @Composable NetworkStatus() exibe o status da conexão e é redesenhado automaticamente nas mudanças. Isso libera o desenvolvedor de gerenciar manualmente callbacks e o ciclo de vida de Activity/Fragment.

NetworkCallback e tratamento de mudanças de rede

ConnectivityManager.NetworkCallback é uma classe abstrata com métodos que são chamados pelo sistema quando o estado da rede muda. onAvailable(Network) é chamado quando uma rede se torna disponível. O aplicativo recebe um objeto Network que pode ser usado para vincular sockets através de Network.bindSocket(). onLost(Network) é chamado quando uma rede se torna indisponível. O aplicativo deve alternar para dados locais ou mostrar uma mensagem de falta de conexão. onCapabilitiesChanged(Network, NetworkCapabilities) é chamado quando as características da rede mudam (por exemplo, ao alternar de Wi-Fi para dados móveis).

O tratamento adequado de mudanças de rede requer considerar o ciclo de vida do componente. O callback deve ser registrado em onStart()/onResume() e cancelado em onStop()/onPause(). Se o callback não for cancelado, ele pode continuar executando após a Activity ser destruída, causando vazamentos de memória e possível NullPointerException quando o callback tentar atualizar a UI de um componente destruído. Use lifecycleScope ou repeatOnLifecycle para gerenciamento automático de registro. No Jetpack Compose, use DisposableEffect para registrar e cancelar o callback.

Tratamento de portal cativo é uma característica importante do ConnectivityManager a partir do Android 10. CAPTIVE_PORTAL é um cenário onde uma rede Wi-Fi está disponível mas requer autenticação através de uma página web (aeroportos, hotéis, cafés). NetworkCapabilities.NET_CAPABILITY_VALIDATED indica que a rede tem acesso completo à internet. Se NET_CAPABILITY_VALIDATED estiver ausente, o aplicativo pode abrir um navegador para autenticação do portal cativo. O método isCaptivePortal(), adicionado no Android 11 (API 30), é usado para detectar portais cativos.

Rede para propósitos específicos (NetworkRequest)

ConnectivityManager permite solicitar uma rede para propósitos específicos através de requestNetwork() e bindProcessToNetwork(). Por exemplo, um aplicativo para baixar arquivos grandes pode solicitar uma rede Wi-Fi mesmo se os dados móveis estiverem ativos. Para isso, um NetworkRequest é criado com addTransportType(TRANSPORT_WIFI), e quando o Wi-Fi estiver disponível, o sistema chama onAvailable(). O aplicativo vincula os sockets a esta rede através de network.bindSocket() ou OkHttp com um objeto Network configurado. Isso fornece controle flexível sobre o uso das interfaces de rede.

Exemplo de implementação em Kotlin

Vamos ver um exemplo completo do uso de ConnectivityManager com a API moderna (NetworkCallback) na Clean Architecture. NetworkMonitor é uma classe wrapper em torno do ConnectivityManager que fornece o status da rede de forma reativa através de StateFlow. O ViewModel se inscreve neste Flow e passa o estado para a UI. O Repository usa NetworkMonitor para tomar decisões sobre solicitações de rede. Esta abordagem garante testabilidade e isolamento das dependências da plataforma.

O exemplo abaixo mostra como usar corretamente o ConnectivityManager com registerDefaultNetworkCallback. A classe NetworkMonitor encapsula o trabalho com o serviço do sistema e fornece um Kotlin Flow limpo. Ela registra o callback na inicialização e o cancela no final do ciclo de vida. A operação assíncrona é garantida através de corrotinas e callbackFlow — uma ponte entre o estilo de callbacks do ConnectivityManager e o estilo reativo Flow do 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
        )
    }
}

Usando NetworkMonitor no ViewModel e Repository

O ViewModel se inscreve em NetworkMonitor.isOnline através de stateIn() e passa o estado para o Compose. O Repository verifica o valor atual de isOnline.value antes de chamar a API: se false — retorna um Flow do Room. Se true — chama a API, salva o resultado no Room e retorna um Flow do Room. O WorkManager usa NetworkType.CONNECTED para restringir tarefas em segundo plano. O teste do NetworkMonitor é feito com um objeto mock de ConnectivityManager e um NetworkCallback falso, permitindo emular qualquer cenário de rede em testes unitários.

Melhores práticas e erros comuns

A primeira regra ao trabalhar com ConnectivityManager é não usar a API obsoleta. getActiveNetworkInfo() está obsoleto desde API 29 e pode retornar dados incorretos em novas versões do Android. Em vez disso, use getActiveNetwork() + getNetworkCapabilities() para verificações únicas e registerDefaultNetworkCallback() para monitoramento contínuo. O método antigo também não distingue entre redes com portal cativo e internet completa, levando a falsos positivos.

A segunda regra é sempre cancelar o registro do callback. Se uma Activity registra um NetworkCallback em onStart() mas não o cancela em onStop(), o callback continua executando após a Activity ser destruída. Isso causa vazamentos de memória e possível NullPointerException quando o callback tenta atualizar a UI de um componente destruído. Use lifecycleScope ou repeatOnLifecycle para gerenciamento automático de registro. No Jetpack Compose, use DisposableEffect para registrar e cancelar o callback.

O terceiro erro comum é verificar apenas a disponibilidade da rede sem considerar sua qualidade. Um simples “tem internet?” não é suficiente para tomar decisões. O aplicativo deve verificar NET_CAPABILITY_NOT_METERED para baixar arquivos grandes, NET_CAPABILITY_NOT_ROAMING para sincronização em segundo plano e NET_CAPABILITY_VALIDATED para confirmar o acesso à internet. Ignorar essas flags leva o aplicativo a tentar baixar vídeo em roaming ou sincronizar dados através de um portal cativo de hotel.

A quarta regra é não usar ConnectivityManager para verificar a disponibilidade de um servidor específico. ConnectivityManager informa o estado da rede no dispositivo, mas não garante que o servidor esteja acessível. Para verificar a disponibilidade de uma API, use uma solicitação HTTP com tempo limite curto ou um Health Check. ConnectivityManager + ping HTTP é uma combinação confiável: primeiro verifique a presença de rede, depois faça uma solicitação leve ao servidor para confirmar a acessibilidade real.

Testando ConnectivityManager

Para testes unitários, use Robolectric com ShadowConnectivityManager, que permite emular estados de rede. Para testes de integração — Android Test Orchestrator com alternância de Modo Avião. Nos testes, verifique cenários: transição de online para offline, aparecimento de Wi-Fi com dados móveis ativos, perda de rede durante uma solicitação, portal cativo, roaming. Para mocking em testes unitários, use uma interface wrapper (por exemplo, NetworkMonitorInterface) que pode ser substituída por um objeto mock sem dependências de plataforma.