헬스 커넥트 시작하기

이 가이드는 헬스 커넥트 버전 1.1.0-alpha12와 호환됩니다.

이 가이드에서는 앱에서 헬스 커넥트를 사용하기 시작하는 방법을 보여줍니다.

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로 이전을 참고하세요.

헬스 커넥트 앱 열기

헬스 커넥트는 더 이상 기본적으로 홈 화면에 표시되지 않습니다. Android 버전에 따라 경로가 다르지만 설정을 통해 헬스 커넥트를 열 수 있습니다.

  • Android 14 이상: 설정 > 보안 및 개인 정보 보호 > 개인 정보 보호 관리 > 헬스 커넥트 로 이동하거나 설정에서 헬스 커넥트 를 검색합니다.
  • Android 13 및 이전 버전: 설정 > 앱 > 헬스 커넥트 로 이동하거나 빠른 설정 메뉴에 헬스 커넥트를 추가합니다.

2단계: 앱에 헬스 커넥트 SDK 추가

헬스 커넥트 SDK는 헬스 커넥트 API를 사용하여 헬스 커넥트 앱의 데이터 저장소에 대해 작업을 실행하는 요청을 전송합니다.

모듈 수준 build.gradle 파일에 헬스 커넥트 SDK 종속 항목을 추가합니다.

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.2.0-alpha04"
  ...
}

최신 버전은 헬스 커넥트 출시를 참고하세요.

카나리아 릴리스 채널 기능 사용

카나리아 출시 채널의 기능을 사용하려면 모듈 수준 build.gradle 파일에서 compileSdk 버전을 수정합니다.

android {
  compileSdkPreview = "CANARY"
}

3단계: 앱 구성

다음 섹션에서는 헬스 커넥트와 통합하도록 앱을 구성하는 방법을 설명합니다.

기능 이용 가능 여부 확인

헬스 커넥트에 새 기능이 추가되더라도 사용자가 항상 헬스 커넥트 버전을 업데이트하는 것은 아닙니다. 기능 이용 가능 여부 API는 헬스 커넥트의 기능을 사용자 기기에서 사용할 수 있는지 확인하고 취할 조치를 결정하는 방법입니다.

기능 이용 가능 여부를 확인하는 기본 함수는 getFeatureStatus()입니다. 이 함수는 정수 상수 FEATURE_STATUS_AVAILABLE 또는 FEATURE_STATUS_UNAVAILABLE을 반환합니다.

@OptIn(ExperimentalFeatureAvailabilityApi::class)
fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}

권한 선언

건강 및 피트니스 데이터에 대한 액세스는 민감합니다. 헬스 커넥트는 읽기 및 쓰기 작업에 보안 계층을 구현하여 사용자 신뢰를 유지합니다.

앱에서 필요한 데이터 유형을 기반으로 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 는 헬스 커넥트 API의 진입점입니다. 앱에서 헬스 커넥트 앱의 데이터 저장소를 사용할 수 있습니다. 기본 저장소 레이어에 대한 연결을 자동으로 관리하고 발신 요청 및 수신 응답의 모든 IPC와 직렬화를 처리합니다.

클라이언트 인스턴스를 가져오려면 먼저 Android 매니페스트에서 헬스 커넥트 패키지 이름을 선언합니다.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

그런 다음 활동에서 헬스 커넥트가 설치되어 있는지 확인합니다. getSdkStatus를 사용하여 설치되어 있는 경우 HealthConnectClient 인스턴스를 가져옵니다.

val availabilityStatus = HealthConnectClient.getSdkStatus(context)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}

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

사용자는 언제든지 권한을 부여하거나 취소할 수 있으므로 앱은 권한을 사용하기 전에 매번 권한을 확인하고 권한이 손실되는 시나리오를 처리해야 합니다.

사용자 온보딩

많은 앱에는 기능 교육 또는 사용자 동의 요청과 같은 맞춤 온보딩 흐름이 있습니다. 헬스 커넥트에서 온보딩 흐름을 실행할 수 있도록 하려면 매니페스트에 다음을 추가합니다.

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

사용자는 앱 내에서가 아니라 헬스 커넥트 앱에서 직접 앱에 대한 연결을 시작할 수 있습니다. 앱에서 데이터를 읽거나 쓰는 권한을 부여하는 것 외에 추가 상호작용이 필요한 경우 온보딩 활동을 제공합니다.

온보딩 활동은 두 번 이상 실행될 수 있습니다(예: 사용자가 나중에 앱에 대한 권한을 취소한 후 다시 연결하는 경우).

5단계: 작업 실행

이제 모든 것이 설정되었으므로 앱에서 읽기 및 쓰기 작업을 실행합니다.

사용자는 앱에서 액세스할 수 있도록 헬스 커넥트와 데이터를 동기화하는 다른 앱을 사용할 수 있습니다. 사용자가 아직 헬스 커넥트에 쓰도록 이러한 앱을 설정하지 않은 경우 Matchmaking API를 사용하여 사용자를 위해 이러한 앱을 원활하게 연결할 수 있습니다.

데이터 쓰기

데이터를 레코드로 구성합니다. 헬스 커넥트에서 사용할 수 있는 데이터 유형 목록을 확인하세요.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

그런 다음 insertRecords를 사용하여 레코드를 작성합니다.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

데이터 읽기

readRecords를 사용하여 데이터를 개별적으로 읽을 수 있습니다.

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}

`aggregate`를 사용하여 집계된 방식으로 데이터를 읽을 수도 있습니다.

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}

동영상 튜토리얼

원활한 통합을 달성하기 위한 권장사항 가이드라인뿐만 아니라 헬스 커넥트 기능에 관해 자세히 설명하는 다음 동영상을 시청하세요.

리소스

나중에 개발에 도움이 되는 다음 리소스를 확인하세요.

다음 단계

일반 워크플로 를 확인하여 다음과 같은 헬스 커넥트에서 작업을 실행하는 방법을 알아보세요.