이 가이드에서는 앱에서 헬스 커넥트를 시작하는 방법을 보여줍니다.
1단계: 헬스 커넥트 앱 준비
헬스 커넥트 앱은 애플리케이션이 헬스 커넥트 SDK를 통해 전송하는 모든 요청을 처리합니다. 이러한 요청에는 데이터 저장과 읽기 및 쓰기 액세스 관리가 포함됩니다.
헬스 커넥트에 대한 액세스는 휴대전화에 설치된 Android 버전에 따라 다릅니다. 다음 섹션에서는 최신 Android 버전을 처리하는 방법을 간략히 설명합니다.
Android 14
Android 14 (API 수준 34)부터 헬스 커넥트는 Android 프레임워크의 일부입니다. 이 버전의 헬스 커넥트는 프레임워크 모듈입니다. 따라서 설정할 필요가 없습니다.
Android 13 및 이전 버전
Android 13(API 수준 33) 이하 버전에서는 헬스 커넥트가 Android 프레임워크의 일부가 아닙니다. 이렇게 하려면 Google Play 스토어에서 헬스 커넥트 앱을 설치해야 합니다.
Android 13 이하에서 앱을 헬스 커넥트와 통합한 후 Android 14로 이전하려면 Android 13에서 14로 이전을 참고하세요.
헬스 커넥트 앱 열기
헬스 커넥트가 더 이상 기본적으로 홈 화면에 표시되지 않습니다. 헬스 커넥트를 열려면 설정 > 앱 > 헬스 커넥트로 이동하거나 빠른 설정 메뉴에 헬스 커넥트를 추가합니다.
또한 헬스 커넥트에서는 기기가 잠겨 있을 때 헬스 커넥트에 저장되는 건강 데이터가 악의적인 행위자로부터 보호되도록 사용자가 PIN, 패턴 또는 비밀번호로 화면 잠금을 사용 설정해야 합니다. 화면 잠금을 설정하려면 설정 > 보안 > 화면 잠금으로 이동합니다.
2단계: 앱에 헬스 커넥트 SDK 추가
헬스 커넥트 SDK는 헬스 커넥트 API를 사용하여 헬스 커넥트 앱의 데이터 스토어에 관한 작업을 실행하는 요청을 전송합니다.
모듈 수준 build.gradle 파일에 헬스 커넥트 SDK 종속 항목을 추가합니다.
dependencies {
...
implementation "androidx.health.connect:connect-client:1.1.0-alph10"
...
}
최신 버전은 헬스 커넥트 출시를 참고하세요.
3단계: 앱 구성
다음 섹션에서는 앱을 Health Connect에 통합하도록 구성하는 방법을 설명합니다.
권한 선언
건강/피트니스 데이터에 대한 액세스는 민감한 정보입니다. 헬스 커넥트는 읽기 및 쓰기 작업을 위한 보안 레이어를 구현하여 사용자 신뢰를 유지합니다.
Play Console에서 앱이 읽고 쓰는 헬스 커넥트 데이터 유형에 대한 액세스를 선언합니다.
앱에서 이러한 필수 데이터 유형을 기반으로 AndroidManifest.xml 파일에서 읽기 및 쓰기 권한을 선언합니다. 이 권한은 Play Console에서 액세스 권한을 선언한 권한과 일치해야 합니다.
헬스 커넥트는 표준 Android 권한 선언 형식을 사용합니다.
<uses-permission> 태그를 사용하여 권한을 할당합니다. 그런 다음 <manifest> 태그 내에 중첩합니다.
<manifest>
<uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
<uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
<uses-permission android:name="android.permission.health.READ_STEPS"/>
<uses-permission android:name="android.permission.health.WRITE_STEPS"/>
<application>
...
</application>
</manifest>
권한 및 해당 데이터 유형의 전체 목록은 데이터 유형 목록을 참고하세요.
앱의 개인정보처리방침 대화상자 표시
Android 매니페스트에는 요청된 권한에 대한 앱의 근거이며 사용자 데이터의 사용 및 처리 방식을 설명하는 앱의 개인정보처리방침을 표시하는 활동이 있어야 합니다.
사용자가 헬스 커넥트 권한 화면에서 개인정보처리방침 링크를 클릭할 때 앱으로 전송되는 ACTION_SHOW_PERMISSIONS_RATIONALE 인텐트를 처리하도록 이 활동을 선언합니다.
...
<application>
...
<!-- For supported versions through Android 13, create an activity to show the rationale
of Health Connect permissions once users click the privacy policy link. -->
<activity
android:name=".PermissionsRationaleActivity"
android:exported="true">
<intent-filter>
<action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
</intent-filter>
</activity>
<!-- For versions starting Android 14, create an activity alias to show the rationale
of Health Connect permissions once users click the privacy policy link. -->
<activity-alias
android:name="ViewPermissionUsageActivity"
android:exported="true"
android:targetActivity=".PermissionsRationaleActivity"
android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
<intent-filter>
<action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
<category android:name="android.intent.category.HEALTH_PERMISSIONS" />
</intent-filter>
</activity-alias>
...
</application>
...
헬스 커넥트 클라이언트 가져오기
HealthConnectClient는 Health Connect API의 진입점입니다.
이를 통해 앱이 헬스 커넥트 앱에서 데이터 스토어를 사용할 수 있습니다. 기본 저장소 레이어에 대한 연결을 자동으로 관리하고 발신 요청 및 수신 응답의 모든 IPC와 직렬화를 처리합니다.
클라이언트 인스턴스를 가져오려면 먼저 Android 매니페스트에서 헬스 커넥트 패키지 이름을 선언합니다.
<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
<package android:name="com.google.android.apps.healthdata" />
</queries>
그런 다음 Activity에서 getSdkStatus를 사용하여 헬스 커넥트가 설치되어 있는지 확인합니다. 설치되어 있으면 HealthConnectClient 인스턴스를 가져옵니다.
val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
// Optionally redirect to package installer to find a provider, for example:
val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
context.startActivity(
Intent(Intent.ACTION_VIEW).apply {
setPackage("com.android.vending")
data = Uri.parse(uriString)
putExtra("overlay", true)
putExtra("callerId", context.packageName)
}
)
return
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient
4단계: 사용자에게 권한 요청
클라이언트 인스턴스를 만든 후 앱은 사용자에게 권한을 요청해야 합니다. 사용자는 언제든지 권한을 부여하거나 거부할 수 있어야 합니다.
이렇게 하려면 필요한 데이터 유형의 권한 집합을 만듭니다. 먼저 집합의 권한이 Android 매니페스트에 선언되어 있는지 확인합니다.
// Create a set of permissions for required data types
val PERMISSIONS =
setOf(
HealthPermission.getReadPermission(HeartRateRecord::class),
HealthPermission.getWritePermission(HeartRateRecord::class),
HealthPermission.getReadPermission(StepsRecord::class),
HealthPermission.getWritePermission(StepsRecord::class)
)
getGrantedPermissions를 사용하여 앱에 이미 필요한 권한이 부여되었는지 확인합니다. 그렇지 않은 경우 createRequestPermissionResultContract를 사용하여 이러한 권한을 요청합니다. 헬스 커넥트 권한 화면이 표시됩니다.
// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()
val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
if (granted.containsAll(PERMISSIONS)) {
// Permissions successfully granted
} else {
// Lack of required permissions
}
}
suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
val granted = healthConnectClient.permissionController.getGrantedPermissions()
if (granted.containsAll(PERMISSIONS)) {
// Permissions already granted; proceed with inserting or reading data
} else {
requestPermissions.launch(PERMISSIONS)
}
}
사용자는 언제든지 권한을 부여하거나 취소할 수 있으므로 권한이 일정하다고 가정하지 마세요. 앱은 부여된 권한을 주기적으로 확인하고 권한이 상실된 시나리오를 처리해야 합니다.
5단계: 작업 실행
이제 모든 설정이 완료되었으므로 앱에서 읽기 및 쓰기 작업을 실행합니다.
데이터 쓰기
데이터를 레코드로 구성합니다. 헬스 커넥트에서 사용할 수 있는 데이터 유형 목록을 확인하세요.
val stepsRecord = StepsRecord(
count = 120,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET,
)
그런 다음 insertRecords를 사용하여 레코드를 작성합니다.
suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
try {
val stepsRecord = StepsRecord(
count = 120,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET,
)
healthConnectClient.insertRecords(listOf(stepsRecord))
} catch (e: Exception) {
// Run error handling here
}
}
데이터 읽기
readRecords를 사용하여 데이터를 개별적으로 읽을 수 있습니다.
suspend fun readStepsByTimeRange(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
try {
val response =
healthConnectClient.readRecords(
ReadRecordsRequest(
StepsRecord::class,
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
for (stepRecord in response.records) {
// Process each step record
}
} catch (e: Exception) {
// Run error handling here.
}
}
aggregate를 사용하여 집계된 방식으로 데이터를 읽을 수도 있습니다.
suspend fun aggregateSteps(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
try {
val response = healthConnectClient.aggregate(
AggregateRequest(
metrics = setOf(StepsRecord.COUNT_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
// The result may be null if no data is available in the time range
val stepCount = response[StepsRecord.COUNT_TOTAL]
} catch (e: Exception) {
// Run error handling here
}
}
동영상 튜토리얼
헬스 커넥트 기능에 관한 자세한 내용과 원활한 통합을 위한 권장사항 가이드라인을 설명하는 동영상을 시청하세요.
리소스
나중에 개발에 도움이 되는 다음 리소스를 확인하세요.
- 헬스 커넥트 SDK (Jetpack에서 사용 가능): 헬스 커넥트 API를 사용하려면 애플리케이션에 이 SDK를 포함합니다.
- API 참조: Health Connect API의 Jetpack 참조를 살펴보세요.
- 데이터 유형 사용 선언: Play Console에서 앱이 읽고 쓰는 헬스 커넥트 데이터 유형에 대한 액세스를 선언합니다.
- GitHub 코드 샘플 및 Codelab(선택사항): 시작하는 데 도움이 되는 GitHub 코드 샘플 저장소 및 Codelab 실습을 참고하세요.
다음 단계
일반 워크플로에서 다음과 같은 헬스 커넥트 작업을 실행하는 방법을 알아보세요.