Connectivity Manager: 개념, 방법 및 연결 모니터링

Connectivity Manager란?

ConnectivityManager는 Android 운영 체제의 시스템 서비스로, Context.getSystemService(Context.CONNECTIVITY_SERVICE)를 통해 접근할 수 있습니다. 기기의 네트워크 연결에 대한 정보를 얻고, 네트워크 변경을 모니터링하며, 애플리케이션의 네트워크 요청을 관리하기 위한 API를 제공합니다. Connectivity Manager는 플랫폼의 첫 번째 버전(API Level 1)부터 Android Framework의 일부였으며, 수십 년에 걸쳐 단순한 getActiveNetworkInfo()에서 NetworkCallback 및 NetworkRequest를 사용한 최신 반응형 모델로 크게 변화했습니다.

Connectivity Manager의 주요 기능은 다음과 같습니다: 활성 네트워크 연결 확인, 네트워크 유형(Wi-Fi, 모바일 데이터, Ethernet, Bluetooth, VPN) 결정, 실시간 네트워크 상태 변경 모니터링, 대역폭 및 지연 시간 정보 획득, 애플리케이션의 네트워크 요청 관리. ConnectivityManager는 WorkManager 및 Repository와 함께 Offline-First 아키텍처, 적응형 콘텐츠 로딩 및 연결 품질에 따른 애플리케이션 최적화를 구현하는 데 사용됩니다.

Android 10(API 29)부터 Google은 ConnectivityManager 작업 방식을 변경했습니다. getActiveNetworkInfo() 메서드는 사용 중단으로 선언되었으며, 대신 NetworkRequest와 함께 registerDefaultNetworkCallback() 또는 registerNetworkCallback()을 사용하는 것이 권장됩니다. 새 API는 캡티브 포털(인증이 필요한 Wi-Fi) 감지 및 연결 품질 평가를 포함한 더 자세한 네트워크 정보를 제공합니다. ConnectivityManager는 Jetpack 제품군과도 통합되어 있습니다. ConnectivityManager 라이브러리는 2024년에 Compose 애플리케이션에서 네트워크 모니터링을 간소화하기 위해 Jetpack의 일부로 출시되었습니다.

애플리케이션 아키텍처에서 Connectivity Manager의 역할

최신 Android 아키텍처에서 Connectivity Manager는 네트워크 요청에 대한 결정을 내리기 위해 Repository 또는 UseCase 수준에서 사용됩니다. Repository 계층은 API를 호출하기 전에 네트워크 상태를 확인합니다. 네트워크를 사용할 수 없으면 로컬 저장소(Room)에서 데이터를 반환합니다. 네트워크를 사용할 수 있으면 서버에 요청하고 결과를 Room에 저장합니다. ViewModel은 Room의 Flow를 구독하며 네트워크 상호 작용의 세부 사항을 알지 못합니다 — 이를 통해 각 계층을 독립적으로 테스트할 수 있습니다.

Connectivity Manager 작동 방식

Connectivity Manager는 Linux 커널의 네트워크 인터페이스와 상호 작용하는 connectivity 시스템 서비스로부터 네트워크 상태 정보를 얻습니다. 기기가 Wi-Fi에 연결하거나 모바일 데이터를 켜면 커널이 시스템 서비스에 알리고, 시스템 서비스는 내부 상태를 업데이트하고 등록된 모든 콜백에 알립니다. ConnectivityManager의 아키텍처는 Observer 패턴을 기반으로 합니다. 애플리케이션이 NetworkCallback을 등록하고 네트워크의 모든 변경 사항(연결 설정, 연결 끊김, 네트워크 유형 변경, 품질 저하)에 대한 알림을 받습니다.

최신 ConnectivityManager API는 NetworkRequest를 사용하여 네트워크 이벤트를 필터링합니다. NetworkRequest를 사용하면 네트워크 요구 사항(Transport.WIFI, Transport.CELLULAR, Transport.ETHERNET 등의 전송, NetworkCapabilities.NET_CAPABILITY_INTERNET 등의 인터넷 기능 및 기타 기준)을 지정할 수 있습니다. 대용량 파일 다운로드를 위해 Wi-Fi만 필요한 애플리케이션은 Transport.WIFI로 NetworkRequest를 만들고 콜백을 등록합니다. 시스템은 Wi-Fi 연결이 변경될 때만 애플리케이션에 알리고 모바일 네트워크 이벤트는 무시합니다.

Android 12+에서 Connectivity Manager의 중요한 기능은 기능 기반 네트워킹입니다. 애플리케이션은 단순히 “인터넷이 있습니까?”를 확인하는 것이 아니라 어떤 유형의 트래픽을 사용할 수 있는지 평가할 수 있습니다. 예를 들어, NET_CAPABILITY_NOT_METERED는 무제한 연결(Wi-Fi)을 나타내고, NET_CAPABILITY_NOT_ROAMING은 기기가 로밍 중이 아님을 나타냅니다. 이를 통해 Wi-Fi에서만 비디오 다운로드, 로밍 중 동기화 연기, 중요한 요청에만 모바일 데이터 사용 등의 결정을 내릴 수 있습니다.

Connectivity Manager 권한

Android 애플리케이션에서 Connectivity Manager를 사용하려면 권한이 필요합니다. ACCESS_NETWORK_STATE는 네트워크 정보를 읽기 위한 필수 권한으로, AndroidManifest.xml에 선언됩니다. 이 권한이 없으면 ConnectivityManager는 getActiveNetwork()에 대해 null을 반환하고 콜백을 호출하지 않습니다. 네트워크 작업을 수행하려면 INTERNET 권한도 필요합니다. Android 10(API 29)부터 애플리케이션은 추가 런타임 권한 없이 네트워크 상태를 확인할 수 있습니다 — ACCESS_NETWORK_STATE는 일반 권한이며 설치 시 자동으로 부여됩니다.

Connectivity Manager의 주요 메서드

최신 Connectivity Manager는 네트워크 작업을 위한 몇 가지 주요 메서드를 제공합니다. getActiveNetwork()(API 23+)는 현재 활성 네트워크의 Network 객체를 반환하거나 기기가 연결되지 않은 경우 null을 반환합니다. 이 메서드는 콜백이 필요 없으며 일회성 확인에 적합합니다. Network 객체는 NetworkCapabilities에 전달하여 전송 유형, 미터링 상태, 로밍, 인터넷 기능 및 기타 특성에 대한 자세한 정보를 얻을 수 있습니다.

registerDefaultNetworkCallback()(API 24+)은 네트워크 모니터링의 기본 방법입니다. 애플리케이션은 기본 네트워크(애플리케이션이 트래픽을 보내는 네트워크)의 변경 사항이 있을 때 호출되는 콜백을 등록합니다. 콜백은 소켓 및 HTTP 클라이언트를 바인딩하는 데 사용할 수 있는 Network 객체를 받습니다. 이 메서드는 사용 중단된 getActiveNetworkInfo()를 대체하며 폴링 없이 반응형 네트워크 모니터링을 제공합니다.

registerNetworkCallback()(API 21+)은 NetworkRequest를 통해 특정 네트워크 유형의 변경 사항을 구독할 수 있습니다. 예를 들어, 애플리케이션은 new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build()를 사용하여 Wi-Fi 네트워크만 추적할 수 있습니다. 시스템은 모바일 네트워크 이벤트에 영향을 주지 않고 Wi-Fi 연결/해제에 대해 애플리케이션에 알립니다. NetworkCapabilities.getLinkDownstreamBandwidthKbps()는 kbit/s 단위의 다운스트림 대역폭 추정치를 반환하여 연결 속도에 맞게 콘텐츠 품질을 조정할 수 있습니다.

Jetpack Compose에서 ConnectivityManager

Jetpack Connectivity 라이브러리(androidx.core:core-ktx)는 Compose에서 ConnectivityManager로 작업하기 위한 편리한 확장 기능을 제공합니다. ConnectivityManager.observeAsState() 함수는 네트워크가 변경될 때 업데이트되는 State을 반환합니다. @Composable NetworkStatus() 구성 요소는 연결 상태를 표시하고 변경 시 자동으로 다시 그려집니다. 이렇게 하면 개발자가 콜백 및 Activity/Fragment 수명 주기를 수동으로 관리할 필요가 없습니다.

NetworkCallback 및 네트워크 변경 처리

ConnectivityManager.NetworkCallback은 네트워크 상태가 변경될 때 시스템에서 호출하는 메서드가 있는 추상 클래스입니다. onAvailable(Network) — 네트워크를 사용할 수 있을 때 호출됩니다. 애플리케이션은 Network.bindSocket()을 통해 소켓을 바인딩하는 데 사용할 수 있는 Network 객체를 받습니다. onLost(Network) — 네트워크를 사용할 수 없게 될 때 호출됩니다. 애플리케이션은 로컬 데이터로 전환하거나 연결 없음 메시지를 표시해야 합니다. onCapabilitiesChanged(Network, NetworkCapabilities) — 네트워크 특성이 변경될 때 호출됩니다(예: Wi-Fi에서 모바일 데이터로 전환 시).

네트워크 변경을 올바르게 처리하려면 구성 요소 수명 주기를 고려해야 합니다. 콜백은 등록되어야 합니다 onStart()/onResume()에서 등록하고 onStop()/onPause()에서 해제해야 합니다. 콜백이 해제되지 않으면 Activity가 소멸된 후에도 계속 실행되어 메모리 누수와 소멸된 구성 요소의 UI를 업데이트하려고 할 때 NullPointerException이 발생할 수 있습니다. 자동 등록 관리를 위해 lifecycleScope 또는 repeatOnLifecycle을 사용하세요. Jetpack Compose에서는 DisposableEffect를 사용하여 콜백을 등록하고 해제합니다.

캡티브 포털 처리는 Android 10부터 ConnectivityManager의 중요한 기능입니다. CAPTIVE_PORTAL은 Wi-Fi 네트워크를 사용할 수 있지만 웹 페이지를 통한 인증이 필요한 시나리오입니다(공항, 호텔, 카페). NetworkCapabilities.NET_CAPABILITY_VALIDATED는 네트워크에 완전한 인터넷 액세스가 있음을 나타냅니다. NET_CAPABILITY_VALIDATED가 없으면 애플리케이션은 캡티브 포털 인증을 위해 브라우저를 열 수 있습니다. Android 11(API 30)에 추가된 isCaptivePortal() 메서드는 캡티브 포털을 감지하는 데 사용됩니다.

특정 목적을 위한 네트워크(NetworkRequest)

ConnectivityManager는 requestNetwork() 및 bindProcessToNetwork()를 통해 특정 목적을 위한 네트워크를 요청할 수 있습니다. 예를 들어, 대용량 파일을 다운로드하는 애플리케이션은 모바일 데이터가 활성화된 경우에도 Wi-Fi 네트워크를 요청할 수 있습니다. 이를 위해 addTransportType(TRANSPORT_WIFI)로 NetworkRequest를 만들고 Wi-Fi를 사용할 수 있게 되면 시스템이 onAvailable()을 호출합니다. 애플리케이션은 network.bindSocket() 또는 구성된 Network 객체가 있는 OkHttp를 통해 이 네트워크에 소켓을 바인딩합니다. 이를 통해 네트워크 인터페이스 사용을 유연하게 제어할 수 있습니다.

Kotlin 구현 예제

Clean Architecture에서 최신 API(NetworkCallback)를 사용한 ConnectivityManager의 전체 예제를 살펴보겠습니다. NetworkMonitor는 ConnectivityManager를 래핑하는 클래스로, StateFlow를 통해 반응형 네트워크 상태를 제공합니다. ViewModel은 이 Flow를 구독하고 상태를 UI에 전달합니다. Repository는 NetworkMonitor를 사용하여 네트워크 요청에 대한 결정을 내립니다. 이 접근 방식은 테스트 용이성과 플랫폼 종속성 격리를 보장합니다.

아래 예제는 registerDefaultNetworkCallback과 함께 ConnectivityManager를 올바르게 사용하는 방법을 보여줍니다. NetworkMonitor 클래스는 시스템 서비스와의 작업을 캡슐화하고 깔끔한 Kotlin Flow을 제공합니다. 시작 시 콜백을 등록하고 수명 주기 종료 시 해제합니다. 비동기 작업은 코루틴과 callbackFlow — ConnectivityManager의 콜백 스타일과 Kotlin의 반응형 Flow 스타일 간의 브리지 — 를 통해 보장됩니다.

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
        )
    }
}

ViewModel 및 Repository에서 NetworkMonitor 사용

ViewModel은 stateIn()을 통해 NetworkMonitor.isOnline을 구독하고 상태를 Compose에 전달합니다. Repository는 API를 호출하기 전에 현재 isOnline.value를 확인합니다. false이면 Room에서 Flow를 반환합니다. true이면 API를 호출하고 결과를 Room에 저장한 다음 Room에서 Flow를 반환합니다. WorkManager는 백그라운드 작업을 제한하기 위해 NetworkType.CONNECTED를 사용합니다. NetworkMonitor 테스트는 mock ConnectivityManager 객체와 fake NetworkCallback을 사용하여 단위 테스트에서 모든 네트워크 시나리오를 에뮬레이트할 수 있습니다.

모범 사례 및 일반적인 실수

ConnectivityManager 작업의 첫 번째 규칙은 사용 중단된 API를 사용하지 않는 것입니다. getActiveNetworkInfo()는 API 29부터 사용 중단되었으며 최신 Android 버전에서 잘못된 데이터를 반환할 수 있습니다. 대신 일회성 확인에는 getActiveNetwork() + getNetworkCapabilities()를, 지속적인 모니터링에는 registerDefaultNetworkCallback()을 사용하세요. 이전 메서드는 캡티브 포털이 있는 네트워크와 완전한 인터넷이 있는 네트워크를 구분하지 못하여 오탐지를 유발합니다.

두 번째 규칙은 항상 콜백 등록을 취소하는 것입니다. Activity가 onStart()에서 NetworkCallback을 등록했지만 onStop()에서 취소하지 않으면 콜백이 Activity 소멸 후에도 계속 실행됩니다. 이로 인해 메모리 누수와 소멸된 구성 요소의 UI를 업데이트하려고 할 때 NullPointerException이 발생할 수 있습니다. 자동 등록 관리를 위해 lifecycleScope 또는 repeatOnLifecycle을 사용하세요. Jetpack Compose에서는 DisposableEffect를 사용하여 콜백을 등록하고 해제합니다.

세 번째 일반적인 실수는 품질을 고려하지 않고 네트워크 가용성만 확인하는 것입니다. 단순한 “인터넷이 있습니까?”만으로는 결정을 내리기에 충분하지 않습니다. 애플리케이션은 대용량 파일 다운로드를 위해 NET_CAPABILITY_NOT_METERED, 백그라운드 동기화를 위해 NET_CAPABILITY_NOT_ROAMING, 인터넷 액세스 확인을 위해 NET_CAPABILITY_VALIDATED를 확인해야 합니다. 이러한 플래그를 무시하면 애플리케이션이 로밍 중에 비디오를 다운로드하거나 호텔의 캡티브 포털을 통해 데이터를 동기화하려고 시도합니다.

네 번째 규칙은 특정 서버의 가용성을 확인하기 위해 ConnectivityManager를 사용하지 않는 것입니다. ConnectivityManager는 기기의 네트워크 상태를 보고하지만 서버에 접근할 수 있다는 것을 보장하지 않습니다. API 가용성을 확인하려면 짧은 시간 제한이 있는 HTTP 요청 또는 상태 확인을 사용하세요. ConnectivityManager + HTTP ping은 안정적인 조합입니다. 먼저 네트워크 존재를 확인한 다음 서버에 가벼운 요청을 보내 실제 접근 가능성을 확인합니다.

ConnectivityManager 테스트

단위 테스트의 경우 네트워크 상태를 에뮬레이트할 수 있는 ShadowConnectivityManager와 함께 Robolectric을 사용하세요. 통합 테스트의 경우 비행기 모드 전환과 함께 Android Test Orchestrator를 사용하세요. 테스트에서는 다음 시나리오를 확인합니다: 온라인에서 오프라인으로 전환, 모바일 데이터 활성 시 Wi-Fi 나타남, 요청 중 네트워크 손실, 캡티브 포털, 로밍. 단위 테스트에서 모킹을 위해 플랫폼 종속성 없이 mock 객체로 대체할 수 있는 래퍼 인터페이스(예: NetworkMonitorInterface)를 사용하세요.