헬스 커넥트 시작하기

이 가이드에서는 앱에서 헬스 커넥트를 사용하는 방법을 설명합니다.

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는 Health Connect API를 사용하여 헬스 커넥트 앱의 데이터 스토어를 대상으로 작업을 실행하는 요청을 전송합니다.

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

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alpha02"
  ...
}

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

3단계: 앱 구성

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

권한 선언

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

필요한 데이터 유형에 따라 AndroidManifest.xml 파일에 대한 읽기 및 쓰기 권한을 선언합니다. 양식을 작성한 후 액세스를 요청한 권한 집합을 사용해야 합니다.

헬스 커넥트는 표준 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 매니페스트에는 앱의 개인정보처리방침을 표시하는 Activity가 있어야 합니다. 이는 사용자 데이터의 사용 및 처리 방식을 설명하는 앱의 요청된 권한 근거입니다.

사용자가 헬스 커넥트 권한 화면에서 개인정보처리방침 링크를 클릭할 때 앱으로 전송되는 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>

그런 다음 활동에서 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에서 사용 가능): Health Connect API를 사용하려면 이 SDK를 애플리케이션에 포함하세요.
  • API 참조: 헬스 커넥트 API에 관한 Jetpack 참조를 확인하세요.
  • API 요청 개발자 선언 양식: 데이터 유형 읽기 및 쓰기 액세스 권한을 요청하려면 이 양식을 사용하세요. 자세한 내용은 헬스 커넥트 데이터 유형 액세스 요청을 참고하세요.
  • 선택적 GitHub 코드 샘플 및 Codelab: 시작하는 데 도움이 되는 GitHub 코드 샘플 저장소Codelab 연습을 참고하세요.

다음 단계

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