이전 목록으로
#Android#Kotlin

Android 위치 권한과 FusedLocationProvider 실전 정리: 현재 위치·지속 추적·GPS 설정

Jetpack Compose 앱에서 Android 위치 권한을 요청하고, Fused Location Provider로 캐시 위치·일회성 현재 위치·지속 위치 업데이트를 처리하는 흐름을 정리한다. Android 12의 대략적·정확한 위치 선택, 백그라운드 위치 정책, GPS 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.

Jetpack Compose 앱에서 위치 기록, 권한 관리와 기기 위치 설정 확인을 함께 구현하는 흐름을 살펴본다. 예제의 SDK 버전과 패키지명은 각 프로젝트 정책에 맞춰 선택한다.

먼저 구분해야 할 세 가지

위치 기능은 다음 세 조건을 별도로 확인해야 한다.

구분 질문 대표 API
앱 권한 사용자가 앱에 위치 접근을 허용했는가? RequestMultiplePermissions
기기 설정 GPS·Wi-Fi 스캔 등 필요한 설정이 켜져 있는가? SettingsClient
앱 상태 화면이 보이는 동안만 추적하는가, 백그라운드에서도 추적하는가? Activity 생명주기·Foreground Service

권한이 허용되어도 기기의 위치 기능이 꺼져 있으면 현재 위치를 얻지 못할 수 있다. 반대로 위치 기능이 켜져 있어도 앱 권한이 없으면 위치 API를 호출할 수 없다.

전체 기능 흐름

flowchart TD
    A[앱 실행] --> B[LocationRecorder 생성]
    B --> C{포그라운드 위치 권한?}
    C -- 없음 --> D[COARSE·FINE 권한 요청]
    C -- 있음 --> E[위치 설정 확인]
    D --> F{대략 또는 정확 권한 허용?}
    F -- 아니오 --> G[거부 UI·설정 안내]
    F -- 예 --> E
    E --> H{설정 충족?}
    H -- 예 --> I[위치 업데이트 시작]
    H -- 해결 가능 --> J[위치 설정 시스템 화면]
    J --> I

MainActivity.onCreate() 진입 흐름

  1. LocationRecorder를 생성한다.
  2. ACCESS_COARSE_LOCATION 또는 ACCESS_FINE_LOCATION이 있는지 확인한다.
  3. 권한이 없으면 런타임 권한을 요청한다.
  4. 권한이 있거나 새로 허용되면 checkLocationSetting()을 호출한다.
  5. 저장된 requestingLocationUpdates를 복원한다.
  6. Compose UI를 구성한다.

기존 흐름처럼 onCreate()마다 무조건 위치 설정을 확인하고 추적을 시작한다면 Bundle에 requestingLocationUpdates를 저장하는 의미가 약해진다. 이 값은 단순히 “과거에 추적 중이었다”가 아니라 사용자가 현재 추적을 원한다는 의도를 나타내도록 설계하는 편이 낫다.

의존성과 Manifest

// app/build.gradle.kts
dependencies {
    implementation("com.google.android.gms:play-services-location:<version>")
}
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- 핵심 기능상 백그라운드 위치가 반드시 필요할 때만 선언 -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

화면이 보이는 동안만 위치를 얻는 앱이라면 ACCESS_BACKGROUND_LOCATION을 선언하지 않는다. 권한은 사용할 수 있다는 이유가 아니라 실제 사용자 기능에 필요한 최소 범위로 요청해야 한다.

포그라운드 위치 권한 요청

Android 12(API 31) 이상에서는 정확한 위치를 원하더라도 FINE과 COARSE를 함께 요청해야 한다. 사용자는 이 요청에서 대략적인 위치만 허용할 수 있다.

private val locationPermissionLauncher =
    registerForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions()
    ) { result ->
        val coarseGranted =
            result[Manifest.permission.ACCESS_COARSE_LOCATION] == true
        val fineGranted =
            result[Manifest.permission.ACCESS_FINE_LOCATION] == true

        when {
            fineGranted -> {
                // 정확한 위치 사용 가능
                checkLocationSetting()
            }
            coarseGranted -> {
                // 대략적인 위치만 사용 가능
                checkLocationSetting()
            }
            else -> {
                // 거부 상태 UI 표시
            }
        }
    }

private fun requestForegroundLocationPermission() {
    locationPermissionLauncher.launch(
        arrayOf(
            Manifest.permission.ACCESS_COARSE_LOCATION,
            Manifest.permission.ACCESS_FINE_LOCATION,
        )
    )
}

권한 확인 함수도 정확한 위치만 검사하면 안 된다. 사용자가 대략적인 위치만 허용했을 때도 위치 기능이 동작할 수 있도록 두 상태를 분리한다.

fun hasForegroundLocationPermission(context: Context): Boolean {
    val coarseGranted = ContextCompat.checkSelfPermission(
        context,
        Manifest.permission.ACCESS_COARSE_LOCATION,
    ) == PackageManager.PERMISSION_GRANTED

    val fineGranted = ContextCompat.checkSelfPermission(
        context,
        Manifest.permission.ACCESS_FINE_LOCATION,
    ) == PackageManager.PERMISSION_GRANTED

    return coarseGranted || fineGranted
}

fun hasPreciseLocationPermission(context: Context): Boolean =
    ContextCompat.checkSelfPermission(
        context,
        Manifest.permission.ACCESS_FINE_LOCATION,
    ) == PackageManager.PERMISSION_GRANTED

LocationRequest의 10_000L 의미

private val locationRequest = LocationRequest.Builder(
    Priority.PRIORITY_HIGH_ACCURACY,
    10_000L,
)
    .setMinUpdateIntervalMillis(5_000L)
    .build()

두 번째 매개변수 10_000L은 희망 업데이트 간격이다. 정확히 10초마다 콜백이 온다는 보장은 없다. 시스템은 센서 상태, 다른 앱의 위치 요청, 절전 모드와 백그라운드 제한에 따라 더 빠르거나 느리게 결과를 전달할 수 있다.

  • setMinUpdateIntervalMillis(5_000L): 다른 앱 때문에 더 빠른 위치가 생성되더라도 이보다 짧은 간격의 전달은 제한한다.
  • PRIORITY_HIGH_ACCURACY: 가능한 높은 정확도를 요청한다. GPS만 강제하는 옵션은 아니며 Fused Location Provider가 여러 신호를 종합한다.
  • 대략적 위치만 허용된 상태에서는 높은 정확도를 요청해도 앱이 받는 결과는 대략적 위치로 제한된다.

캐시 위치와 현재 위치

lastLocation

lastLocation은 캐시된 마지막 위치를 빠르게 반환한다. 오래된 값이거나 null일 수 있으므로 현재 위치가 반드시 필요한 기능의 유일한 데이터로 사용하면 안 된다.

@RequiresPermission(
    anyOf = [
        Manifest.permission.ACCESS_COARSE_LOCATION,
        Manifest.permission.ACCESS_FINE_LOCATION,
    ]
)
fun getLastLocation(onResult: (Location?) -> Unit) {
    fusedLocationClient.lastLocation
        .addOnSuccessListener(onResult)
        .addOnFailureListener { error ->
            Log.e("LocationRecorder", "lastLocation failed", error)
            onResult(null)
        }
}

getCurrentLocation()

getCurrentLocation()은 허용한 캐시 나이 안의 위치가 있으면 재사용하고, 그렇지 않으면 새 위치 획득을 시도한다. 반환되는 Task<Location?>의 결과를 반드시 소비해야 한다.

private var currentLocationCancellation: CancellationTokenSource? = null

@RequiresPermission(
    anyOf = [
        Manifest.permission.ACCESS_COARSE_LOCATION,
        Manifest.permission.ACCESS_FINE_LOCATION,
    ]
)
fun getCurrentLocation(onResult: (Location?) -> Unit) {
    currentLocationCancellation?.cancel()
    val cancellation = CancellationTokenSource()
    currentLocationCancellation = cancellation

    val request = CurrentLocationRequest.Builder()
        .setPriority(Priority.PRIORITY_HIGH_ACCURACY)
        .setDurationMillis(10_000L)
        .setMaxUpdateAgeMillis(60_000L)
        .build()

    fusedLocationClient
        .getCurrentLocation(request, cancellation.token)
        .addOnSuccessListener(onResult)
        .addOnFailureListener { error ->
            Log.e("LocationRecorder", "current location failed", error)
            onResult(null)
        }
}

여기서 setDurationMillis(10_000L)는 새 위치를 기다리는 최대 시간이고, setMaxUpdateAgeMillis(60_000L)는 최대 60초 이내 캐시를 허용한다.

지속 위치 업데이트

private val locationCallback = object : LocationCallback() {
    override fun onLocationResult(result: LocationResult) {
        result.locations.forEach { location ->
            Log.d(
                "LocationRecorder",
                "lat=${location.latitude}, lng=${location.longitude}, " +
                    "accuracy=${location.accuracy}, time=${location.time}",
            )
        }
    }
}

@RequiresPermission(
    anyOf = [
        Manifest.permission.ACCESS_COARSE_LOCATION,
        Manifest.permission.ACCESS_FINE_LOCATION,
    ]
)
fun startLocationUpdates() {
    fusedLocationClient.requestLocationUpdates(
        locationRequest,
        locationCallback,
        Looper.getMainLooper(),
    )
    requestingLocationUpdates = true
}

fun stopLocationUpdates() {
    fusedLocationClient.removeLocationUpdates(locationCallback)
    requestingLocationUpdates = false
}

@RequiresPermission(allOf = [FINE, COARSE])로 선언하면 두 권한이 모두 필수라는 의미가 된다. 대략적 위치만 허용하는 흐름을 지원하려면 anyOf가 실제 정책과 맞다.

위치 시스템 설정 확인

SettingsClient.checkLocationSettings()는 앱 권한이 아니라 현재 LocationRequest를 만족할 기기 설정이 켜져 있는지 확인한다. 해결 가능한 오류이면 시스템 설정 화면을 표시한다.

deprecated된 startResolutionForResult()와 onActivityResult() 대신 Activity Result API를 사용할 수 있다.

private val locationSettingsLauncher = registerForActivityResult(
    ActivityResultContracts.StartIntentSenderForResult()
) { result ->
    if (result.resultCode == Activity.RESULT_OK &&
        locationRecorder.hasForegroundLocationPermission()
    ) {
        locationRecorder.startLocationUpdates()
    } else {
        // 사용자가 위치 설정 변경을 취소함
    }
}

private fun checkLocationSetting() {
    val request = LocationSettingsRequest.Builder()
        .addLocationRequest(locationRecorder.locationRequest)
        .build()

    LocationServices.getSettingsClient(this)
        .checkLocationSettings(request)
        .addOnSuccessListener {
            if (locationRecorder.hasForegroundLocationPermission()) {
                locationRecorder.startLocationUpdates()
            }
        }
        .addOnFailureListener { error ->
            if (error is ResolvableApiException) {
                val intentSenderRequest = IntentSenderRequest.Builder(
                    error.resolution,
                ).build()
                locationSettingsLauncher.launch(intentSenderRequest)
            }
        }
}

locationRequest를 Activity에서 참조하려면 읽기 전용 프로퍼티로 공개하거나, LocationRecorder가 LocationSettingsRequest 또는 ResolvableApiException만 반환하도록 책임을 나눌 수 있다. 시스템 UI를 실행하는 책임은 Activity가 가지는 편이 테스트하기 쉽다.

Activity 생명주기 연동

화면이 보일 때만 위치를 기록하는 정책이라면 다음처럼 연결할 수 있다.

override fun onResume() {
    super.onResume()
    if (requestingLocationUpdates &&
        locationRecorder.hasForegroundLocationPermission()
    ) {
        checkLocationSetting()
    }
}

override fun onPause() {
    locationRecorder.stopLocationUpdates()
    super.onPause()
}

다만 stopLocationUpdates()가 requestingLocationUpdates = false까지 변경하면 onResume()에서 재개할 의도를 잃는다. 다음 두 상태를 구분하는 편이 명확하다.

  • trackingRequested: 사용자가 추적 기능을 켰는가?
  • updatesRunning: 현재 콜백이 실제 등록되어 있는가?
stateDiagram-v2
    [*] --> Idle
    Idle --> WaitingSetting: 추적 시작
    WaitingSetting --> Running: 권한·설정 충족
    WaitingSetting --> Idle: 취소·거부
    Running --> Paused: onPause
    Paused --> Running: onResume
    Running --> Idle: 사용자가 중지

Compose에서는 장기 상태를 Activity의 일반 변수보다 ViewModel과 StateFlow, 프로세스 재생성에 필요한 값은 SavedStateHandle로 관리하는 방식도 고려한다.

Android 버전별 위치 권한 정책

버전 정책
Android 6(API 23)+ 위험 권한인 위치 권한을 런타임에 요청한다.
Android 10(API 29)+ 백그라운드 위치에 ACCESS_BACKGROUND_LOCATION 선언이 필요하다.
Android 11(API 30)+ 포그라운드와 백그라운드 위치를 동시에 요청하면 시스템이 요청을 무시한다. 백그라운드는 별도 단계에서 시스템 설정을 통해 허용한다.
Android 12(API 31)+ 사용자가 정확한 위치 대신 대략적인 위치만 선택할 수 있다. FINE이 필요하면 COARSE와 함께 요청한다.
Android 14(API 34)+ 위치 Foreground Service를 사용한다면 해당 서비스 타입과 FOREGROUND_SERVICE_LOCATION 권한 등 버전별 FGS 요구사항을 확인한다.

따라서 “위치 권한의 최소 버전은 Android 10”이라는 설명은 정확하지 않다. 일반 위치 런타임 권한은 Android 6부터 적용되며, Android 10은 백그라운드 위치 권한이 별도로 도입된 기준이다.

또한 COARSE는 3km², FINE은 50m처럼 고정 오차를 보장한다고 설명하면 안 된다. 실제 정확도는 기기, 실내외 환경, 센서와 네트워크 상태에 따라 달라진다. Location.accuracy 값을 함께 확인해야 한다.

백그라운드 위치와 Google Play 정책

화면을 벗어난 뒤에도 위치를 계속 수집하는 것은 ACCESS_BACKGROUND_LOCATION 선언 하나로 끝나지 않는다.

  • 백그라운드 위치가 앱의 핵심 기능인지 먼저 판단한다.
  • 포그라운드 권한을 먼저 받은 뒤 백그라운드 권한을 별도로 요청한다.
  • 사용자에게 수집 목적과 사용 방식을 눈에 띄게 고지하고 동의를 받는다.
  • 계속 실행되는 사용자 인지형 작업은 location 타입 Foreground Service와 알림을 검토한다.
  • Google Play Console의 권한 선언, 앱 설명, 데모 자료 등 심사 요구사항을 확인한다.
  • 백그라운드에서는 시스템이 위치 업데이트 빈도를 제한할 수 있다.

단순 분석, 광고, 편의 기능만을 이유로 백그라운드 위치를 요청하면 최소 권한 원칙이나 Google Play 정책을 충족하지 못할 수 있다.

원본 코드에서 보완할 부분

  1. LocationRequest.Builder(..., 10_000L)을 정확한 10초 주기로 설명하지 않는다.
  2. getCurrentLocation()이 반환하는 Task에 성공·실패 리스너를 연결한다.
  3. 사용하지 않는 activity 매개변수를 제거한다.
  4. hasLocationPermission()에서 FINE만 확인하지 않고 COARSE || FINE을 처리한다.
  5. 권한 어노테이션은 요구 정책에 따라 allOf가 아닌 anyOf를 사용한다.
  6. 위치 설정 확인 함수의 불필요한 @SuppressLint("MissingPermission")을 제거한다.
  7. 설정 변경 결과가 RESULT_OK이면 실제 업데이트 시작 흐름으로 연결한다.
  8. deprecated된 startResolutionForResult()와 onActivityResult()를 Activity Result API로 교체한다.
  9. requestingLocationUpdates를 사용자 의도와 실제 실행 상태로 분리한다.
  10. LocationRecorder가 Activity Context를 장기 보관하지 않도록 Application Context 사용 또는 생명주기 범위를 명확히 한다.

테스트 체크리스트

  • 최초 실행에서 대략적 위치만 허용
  • 정확한 위치 허용
  • 권한 거부 및 다시 묻지 않음
  • GPS가 꺼진 상태에서 설정 화면 승인·취소
  • 캐시 위치가 없는 새 기기 또는 에뮬레이터
  • getCurrentLocation() 제한 시간 만료
  • 화면 회전 후 중복 콜백 등록 여부
  • 백그라운드 진입 후 콜백 해제 여부
  • 앱 설정에서 정확한 위치를 대략적 위치로 변경
  • 절전 모드 및 네트워크 단절

관련 문서

목록으로 돌아가기

다른 게시글

#Android#Flutter

현장 Flutter 앱 디버깅에 자주 쓴 ADB 명령어

기기 지정, Logcat, APK 설치, 파일 복사, 포트 reverse를 실기기 점검 흐름으로 정리한다.

#Android#Kotlin

Android 입력 장치 목록 조회하기: 키보드·마우스·HID 스캐너 구분

Android `InputManager`와 `InputDevice` API로 연결된 입력 장치를 조회하고, 키보드·포인터·외부 장치 여부를 판별하는 방법을 정리한다. USB·Bluetooth HID 바코드 스캐너를 일반 키보드와 구분할 때의 한계와 연결 변경 감지 방법도 함께 살펴본다.

#Android#Gradle

Android Release 빌드: APK·AAB·서명·R8까지

`assembleRelease`와 `bundleRelease`의 차이, 릴리스 서명, R8 최적화와 배포 전 검증을 정리한다.