시계는 배터리가 작아서 위치를 어떻게 받느냐가 배터리 지속 시간에 바로 영향을 줘요. Wear OS에서 위치를 얻는 경로는 두 가지예요. 통합 위치 정보 제공자(Fused Location Provider, FLP)와 Wear 건강 관리 서비스(Health Services, WHS)예요. 두 API는 서로 다른 시점을 맡는 관계에 가까워요. 이 글에서는 두 API의 차이를 보고 운동 앱에서 둘을 시점별로 나눠 쓰는 방법을 정리해요.
코드는 health-services-client 1.1.0, play-services-location 21.4.0 기준이에요. 모두 Wear OS 6(API 36) 에뮬레이터에서 실행해 확인했어요.
1. FLP와 WHS의 역할
공식 문서는 쓰임새를 이렇게 나눠요.
| 항목 | FLP | WHS |
|---|---|---|
| 제공 | Google Play 서비스의 FusedLocationProviderClient | Wear OS의 Health Services(ExerciseClient) |
| 맞는 경우 | 위치를 한 번 조회할 때, 기록 없이 계속 받을 때 | 운동처럼 정해진 시간 동안 추적할 때, 심박 같은 다른 센서 데이터도 필요할 때 |
| 위치 출처 | 휴대전화와 시계 중 전력을 덜 쓰는 쪽 | 시계의 GPS 또는 연결된 휴대전화 |
공식 문서는 운동 추적에는 전력 효율이 더 높은 WHS를 쓰라고 권해요. 운동 중 화면이 꺼지면 WHS는 같은 주기로 측정하면서 데이터를 모아 두었다가 덜 자주 보내요. 메인 프로세서를 자주 깨우지 않으려는 거예요. 사용자가 화면을 보면 모아 둔 데이터를 바로 보내요.
FLP는 휴대전화의 위치를 쓸 수도 있어요. GPS가 없는 시계는 휴대전화 위치에 기대므로 연결이 끊기면 위치를 받지 못해요. 계속 위치가 필요한 앱이라면 PackageManager.FEATURE_LOCATION_GPS로 시계에 GPS가 있는지 확인하고 연결이 끊기면 사용자에게 알려야 해요.
2. FLP로 첫 위치 빨리 보여 주기
운동 준비 화면에 들어오면 지도에 시작점부터 보여 주고 싶어요. WHS가 GPS를 잡는 데는 몇 초가 걸리니, 그동안 FLP로 위치를 먼저 얻어 둬요.
private val fusedLocationClient by lazy { LocationServices.getFusedLocationProviderClient(this) }
private val cancellationTokenSource = CancellationTokenSource()
private var hasCurrentLocation = false
private fun showStartPoint() {
fusedLocationClient.lastLocation.addOnSuccessListener { cached: Location? ->
if (cached != null && !hasCurrentLocation) moveMapTo(cached)
}
fusedLocationClient.getCurrentLocation(
Priority.PRIORITY_HIGH_ACCURACY,
cancellationTokenSource.token,
).addOnSuccessListener { location: Location? ->
if (location != null) {
hasCurrentLocation = true
moveMapTo(location)
}
}
}
override fun onDestroy() {
cancellationTokenSource.cancel()
super.onDestroy()
}두 함수는 하는 일이 달라요. lastLocation은 캐시된 마지막 위치를 바로 돌려주고 캐시가 없으면 null이에요. getCurrentLocation은 충분히 최근에 측정한 위치가 있으면 그것을 돌려주고 없으면 새로 측정해요. 시간 안에 위치를 얻지 못하면 null이 와요. 에뮬레이터에서 돌려 보면 lastLocation은 0.3초 안에 돌아왔고(처음 실행할 때는 캐시가 없어서 null), getCurrentLocation은 4초 가까이 걸렸어요. 그래서 캐시 값으로 먼저 보여 주고 새 위치가 오면 바꿔요. 두 요청은 동시에 보내므로, 캐시 값이 새 위치보다 늦게 와도 덮어쓰지 않게 hasCurrentLocation으로 막았어요.
CancellationTokenSource는 화면을 떠날 때 아직 끝나지 않은 getCurrentLocation 요청을 취소하려고 둬요. 이미 응답이 왔다면 취소할 요청이 없어요. 두 함수 모두 위치 권한을 받은 뒤에 불러요.
3. WHS로 운동 중 위치 받기
권한과 포그라운드 서비스
운동 추적은 포그라운드 서비스에서 해요. 공식 문서는 준비 단계를 포함한 운동 내내 포그라운드 서비스를 유지하라고 해요. Activity의 수명 주기에 묶여 있으면 센서 준비가 중간에 끊길 수 있어요.
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.BODY_SENSORS" android:maxSdkVersion="35" />
<uses-permission android:name="android.permission.health.READ_HEART_RATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_HEALTH" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<service
android:name=".ExerciseService"
android:foregroundServiceType="health|location"
android:exported="false" />권한마다 쓰이는 곳이 있어요.
| 권한 | 필요한 곳 |
|---|---|
ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION | 위치 데이터(DataType.LOCATION), isGpsEnabled = true. FINE은 COARSE와 같이 요청 |
ACTIVITY_RECOGNITION | 거리 데이터(DataType.DISTANCE) |
health.READ_HEART_RATE | 심박 데이터. API 35 이하는 BODY_SENSORS |
FOREGROUND_SERVICE_HEALTH, FOREGROUND_SERVICE_LOCATION | health, location 타입의 포그라운드 서비스 |
서비스 타입을 둘 다 적었으니 두 타입의 조건을 모두 채워야 해요. location 타입은 기기의 위치 서비스가 켜져 있고 위치 권한을 받았을 때 시작돼요. health 타입은 이 매니페스트처럼 HIGH_SAMPLING_RATE_SENSORS를 선언하지 않았다면 ACTIVITY_RECOGNITION, health.READ_HEART_RATE 같은 런타임 권한 중 하나가 있어야 시작돼요. 런타임 권한 없이 startForeground를 부르면 SecurityException이 나요. 공식 문서는 준비 전에 LocationManager.isProviderEnabled(GPS_PROVIDER)로 기기의 위치 설정도 확인하라고 해요.
공식 예제의 매니페스트에는 Health Services 패키지를 찾는 <queries>도 있어요. health-services-client의 매니페스트에 이미 들어 있어서, 매니페스트 병합을 쓰면 앱에 넣지 않아도 돼요.
지원 여부 확인
운동 종류, 데이터 타입, 자동 일시정지는 기기마다 지원 여부가 달라요. WHS는 지원하지 않는 설정을 거부하므로 먼저 확인해요.
private suspend fun runningCapabilities(): ExerciseTypeCapabilities? {
val capabilities = exerciseClient.getCapabilities()
if (ExerciseType.RUNNING !in capabilities.supportedExerciseTypes) return null
return capabilities.getExerciseTypeCapabilities(ExerciseType.RUNNING)
}getCapabilities, prepareExercise, startExercise, endExercise는 health-services-client의 suspend 확장 함수예요. prepareExerciseAsync(...).await()처럼 ListenableFuture를 기다리지 않아도 돼요.
콜백을 먼저 등록하고 준비하기
prepareExercise는 운동 시간을 재기 전에 센서를 미리 켜 두는 단계예요. 미리 켤 수 있는 센서는 GPS(DataType.LOCATION)와 심박(DataType.HEART_RATE_BPM) 두 가지예요.
private suspend fun prepare() {
exerciseClient.setUpdateCallback(callback)
val warmUpConfig = WarmUpConfig(
exerciseType = ExerciseType.RUNNING,
dataTypes = setOf(DataType.LOCATION, DataType.HEART_RATE_BPM),
)
exerciseClient.prepareExercise(warmUpConfig)
}준비 중에 바뀌는 위치 상태는 ExerciseUpdateCallback으로 오니, 콜백을 prepareExercise보다 먼저 등록해요. 에뮬레이터에서 콜백을 먼저 등록하면 ACQUIRING이 오고 약 4초 뒤 ACQUIRED_UNTETHERED와 첫 위치가 와요. 준비를 시작하고 5초 뒤에 콜백을 등록하면 등록하는 순간의 상태(ACQUIRED_UNTETHERED)는 받지만, 그 전의 ACQUIRING과 준비 중에 온 위치는 받지 못해요.
사용자가 운동을 시작하지 않고 준비 화면을 떠나면 endExercise()로 센서를 꺼요. 준비 상태로 너무 오래 두면 WHS가 운동을 끝내요(AUTO_END_PREPARE_EXPIRED).
위치 데이터와 상태 받기
콜백에서는 위치와 심박 데이터, 위치 상태를 받아요. 위치 상태는 서비스의 MutableStateFlow에 넣고, 화면은 공개한 locationAvailability를 구독해서 보여 줘요.
private val _locationAvailability = MutableStateFlow(LocationAvailability.UNKNOWN)
val locationAvailability: StateFlow<LocationAvailability> = _locationAvailability.asStateFlow()
private val callback = object : ExerciseUpdateCallback {
override fun onExerciseUpdateReceived(update: ExerciseUpdate) {
update.latestMetrics
.getData(DataType.LOCATION)
.forEach { dataPoint ->
val location: LocationData = dataPoint.value
onLocation(location)
}
update.latestMetrics
.getData(DataType.HEART_RATE_BPM)
.forEach { dataPoint -> onHeartRate(dataPoint.value) }
if (update.exerciseStateInfo.state.isEnded) {
onEnded(update.exerciseStateInfo.endReason)
}
}
override fun onAvailabilityChanged(
dataType: DataType<*, *>,
availability: Availability,
) {
if (availability is LocationAvailability) {
_locationAvailability.value = availability
}
}
override fun onLapSummaryReceived(lapSummary: ExerciseLapSummary) = Unit
override fun onRegistered() = Unit
override fun onRegistrationFailed(throwable: Throwable) = Unit
}onLocation, onHeartRate, onEnded는 데이터를 저장하거나 운동 종료를 처리하는 앱의 함수예요. 공식 문서도 준비 중의 상태를 사용자에게 보여 주고 사용자가 보고 운동을 시작할지 정하게 하라고 해요.
LocationAvailability | 뜻 |
|---|---|
ACQUIRING | 위치를 잡는 중 |
ACQUIRED_TETHERED | 연결된 휴대전화로 위치를 받음 |
ACQUIRED_UNTETHERED | 시계에서 위치를 받음 |
NO_GNSS | 기기의 위치 서비스가 꺼져 있음 |
UNAVAILABLE | 위치를 쓸 수 없음 |
UNKNOWN | 알 수 없음 |
콜백은 운동 내내 등록되어 있어야 해요. 콜백 없이 5분이 지나면 WHS가 운동을 끝내요(AUTO_END_MISSING_LISTENER).
운동 시작
위치가 잡히고 사용자가 시작을 누르면, 기기가 지원하는 설정만 골라 운동을 시작해요.
private suspend fun start(capabilities: ExerciseTypeCapabilities) {
val config = ExerciseConfig(
exerciseType = ExerciseType.RUNNING,
dataTypes = setOf(DataType.LOCATION, DataType.DISTANCE, DataType.HEART_RATE_BPM)
.intersect(capabilities.supportedDataTypes),
isAutoPauseAndResumeEnabled = capabilities.supportsAutoPauseAndResume,
isGpsEnabled = true,
)
exerciseClient.startExercise(config)
}요청할 데이터 타입은 기기가 지원하는 것만 남기고(intersect), 자동 일시정지도 지원할 때만 켜요. 위치 데이터를 받으려면 isGpsEnabled가 true여야 해요. DataType.DISTANCE는 구간마다의 거리라서 누적 거리를 보여 주려면 더하거나 DataType.DISTANCE_TOTAL을 요청해요.
4. 시점별로 나눠 쓰기
운동 앱에서는 두 API를 시점별로 나눠 써요. 공식 문서도 FLP의 위치를 첫 위치로 쓰다가, WHS에서 더 안정적인 위치가 오면 그것으로 바꾸라고 해요.
| 시점 | 쓰는 API | 하는 일 |
|---|---|---|
| 준비 화면 진입 | FLP lastLocation, getCurrentLocation | 지도에 시작점 표시 |
| 운동 준비 | WHS prepareExercise | GPS와 심박 센서 예열, 위치 상태 표시 |
| 운동 중 | WHS startExercise, ExerciseUpdateCallback | 위치, 거리, 심박 수신 |
| 운동 종료 | WHS endExercise | 세션 정리 |
WHS에서 ACQUIRED_* 상태와 위치가 오면 그때부터는 WHS의 위치를 써요. 이 글의 코드는 화면을 떠날 때만 FLP 요청을 취소해요. WHS 위치가 먼저 왔을 때도 취소하려면 화면이 locationAvailability를 구독하다가 ACQUIRED_*를 받을 때 cancel()을 부르면 돼요.
마무리
저는 운동 앱이라면 위치는 WHS에 맡기고, FLP는 준비 화면의 첫 좌표처럼 짧게만 쓰는 편이 맞다고 생각해요. 새로 운동 추적 기능을 만든다면 준비 화면에서 콜백을 등록하고 prepareExercise를 부르는 부분부터 만들어 보기를 권해요.
참고
- Wear OS에서 위치 감지: FLP와 WHS를 고르는 기준
- ExerciseClient로 운동 기록: 지원 여부 확인, 준비, 콜백, 포그라운드 서비스, FLP를 첫 위치로 쓰는 방법
- Health Services 권한
- 포그라운드 서비스 타입:
health,location의 권한 조건 - 위치 권한: FINE과 COARSE를 같이 요청하는 이유
FusedLocationProviderClient레퍼런스- 에뮬레이터의 합성 데이터
- Health Services 릴리스 노트: 라이브러리 매니페스트의
<queries> - health-samples ExerciseSampleCompose: 공식 운동 앱 예제



