실적 계획

앱이 헬스 커넥트와 함께 잘 작동할 수 있도록 다음 권장사항 가이드라인을 준수하는 것이 좋습니다.

데이터 쓰기

앱은 자체 공급된 데이터만 헬스 커넥트에 써야 합니다.

앱의 데이터를 다른 앱에서 가져온 경우 데이터를 헬스 커넥트에 쓰는 것에 대한 책임은 데이터를 소유한 다른 앱에 있습니다.

데이터가 경계 밖에 있을 때 발생하는 오류 또는 내부 시스템 오류와 같은 쓰기 예외를 처리하는 로직을 구현하는 것도 좋습니다. 작업 예약 메커니즘에서 백오프 및 재시도 전략을 적용할 수 있습니다. 헬스 커넥트로의 쓰기 작업이 최종적으로 실패하면 앱이 그 내보내기 지점을 지나서 이동할 수 있어야 합니다. 오류를 기록하고 보고하여 진단을 돕는 것을 잊지 마세요.

데이터를 추적할 때 앱이 데이터를 쓰는 방식에 따라 몇 가지 추천사항이 있습니다.

수동 추적

여기에는 백그라운드에서 지속적으로 걸음 수나 심박수를 기록하는 것과 같이 피트니스 활동 또는 건강 관련 항목을 수동으로 추적하는 앱이 포함됩니다.

앱은 다음과 같은 방법으로 헬스 커넥트에 주기적으로 데이터를 기록해야 합니다.

  • 동기화를 진행할 때마다 새 데이터만 쓰고 마지막 동기화 이후에 수정된 데이터는 업데이트합니다.
  • 쓰기 요청 하나당 최대 1,000개의 레코드를 묶어서 요청합니다.
  • WorkManager를 사용하여 기간이 15분 이상인 백그라운드 작업을 주기적으로 예약합니다.

  • 기기가 유휴 상태이고 배터리 잔량이 충분한 경우에만 실행되도록 작업을 제한합니다.

    val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

능동 추적

여기에는 운동 및 수면과 같은 이벤트 기반 추적 또는 영양과 같은 직접적인 사용자 입력을 실행하는 앱이 포함됩니다. 이러한 기록은 앱이 포그라운드에 있거나 드물게 하루에 몇 번 사용되는 경우에 생성됩니다.

앱은 이벤트의 전체 기간 동안 헬스 커넥트가 계속 실행되지 않도록 해야 합니다.

다음 두 가지 방법 중 하나로 데이터를 헬스 커넥트에 써야 합니다.

  • 이벤트가 완료된 후에 헬스 커넥트에 데이터를 동기화합니다. 예를 들어 사용자가 추적 중인 운동 세션을 종료할 때 데이터를 동기화합니다.
  • 나중에 데이터를 동기화하려면 WorkManager를 사용하여 일회성 작업을 예약합니다.

샘플링 레이트

헬스 커넥트에 데이터를 쓸 때 적절한 샘플링 레이트를 사용하면 저장용량 부하를 줄일 수 있습니다. 예를 들어, 걸음 수 데이터를 얼마나 자주 기록해야 하는지 또는 활성 운동에 어떤 종류의 샘플링 레이트 데이터 유형(예: 속도)을 사용해야 하는지 고려해 보아야 합니다.

모든 데이터 유형에 동일한 샘플링 레이트가 필요한 것은 아닙니다. 걸음 수 데이터를 업데이트하는 경우 매초 업데이트하는 것은 비교적 덜 자주(예: 60초) 업데이트하는 것보다 이득이 없습니다. 하지만 샘플링 레이트가 높을수록 사용자가 자신의 건강/피트니스 데이터를 더 상세하고 세부적으로 확인할 수 있습니다. 샘플링 레이트 빈도는 세부정보와 성능 간의 균형을 유지할 필요가 있습니다.

데이터 동기화

동기화 프로세스에 영향을 주는 요인은 다음과 같습니다.

토큰 만료

사용하지 않은 변경 토큰은 30일 이내에 만료되므로 이러한 경우 정보가 손실되지 않도록 하는 동기화 전략을 사용해야 합니다. 다음 접근 방식을 전략으로 사용할 수 있습니다.

  • 앱 DataStore에서 최근 사용한 레코드 중 헬스 커넥트의 id도 포함하는 레코드를 검색합니다.
  • 특정 타임스탬프로 시작하는 레코드를 헬스 커넥트에서 요청한 다음 레코드를 앱의 DataStore에 삽입하거나 업데이트합니다.
  • 다음에 필요할 때 사용할 수 있도록 변경 토큰을 요청합니다.

권장되는 변경 관리 전략

앱이 무효하거나 만료된 변경 토큰을 받는 경우 로직에서 토큰이 적용되는 방식에 따라 다음 관리 전략을 사용하는 것이 좋습니다.

  • 모든 데이터 읽기 및 중복 삭제. 가장 이상적인 전략입니다.
    • 헬스 커넥트에서 마지막으로 데이터를 읽은 시간의 타임스탬프를 저장합니다.
    • 토큰 만료 시 가장 최근 타임스탬프의 데이터 또는 지난 30일간의 데이터를 모두 다시 읽습니다. 그런 다음 식별자를 사용하여 이전에 읽은 데이터에서 중복 데이터를 삭제합니다.
    • 클라이언트 ID는 데이터 업데이트에 필요하므로 이를 구현하는 것이 좋습니다.
  • 마지막으로 읽은 타임스탬프 이후의 데이터만 읽기. 그러면 변경 토큰 만료 시점 쯤에 데이터 불일치가 발생할 수 있지만 그 기간은 몇 시간에서 최대 이틀 정도 걸릴 만큼 줄어듭니다.
    • 헬스 커넥트에서 마지막으로 데이터를 읽은 시간의 타임스탬프를 저장합니다.
    • 토큰 만료 시 이 타임스탬프 이후의 모든 데이터를 읽습니다.
  • 지난 30일간의 데이터를 삭제한 후 읽기. 이는 첫 번째 통합에서 발생하는 상황에 더 잘 맞습니다.
    • 지난 30일 동안 앱이 헬스 커넥트에서 읽은 모든 데이터를 삭제합니다.
    • 삭제한 다음 이 데이터를 다시 읽습니다.
  • 중복 삭제 없이 지난 30일 동안의 데이터 읽기. 이는 가장 이상적이지 않은 전략이며, 사용자에게 중복 데이터가 표시됩니다.
    • 지난 30일 동안 앱이 헬스 커넥트에서 읽은 모든 데이터를 삭제합니다.
    • 중복된 항목을 허용합니다.

데이터 유형 변경 토큰

앱이 2개 이상의 데이터 유형을 독립적으로 사용하는 경우 각 데이터 유형에 별도의 변경 토큰을 사용하세요. 여러 데이터 유형이 함께 사용되거나 그중 어떠한 것도 사용되지 않는 경우에만 그러한 데이터 유형의 목록과 Changes Sync API를 같이 사용하세요.

포그라운드 읽기

앱은 포그라운드에 있는 동안에만 헬스 커넥트의 데이터를 읽을 수 있습니다. 헬스 커넥트에서 데이터를 동기화할 때 헬스 커넥트에 대한 액세스가 언제든지 중단될 수 있습니다. 예를 들어 앱은 헬스 커넥트에서 대량의 데이터를 읽을 때 동기화 도중 발생하는 중단을 처리하고 다음에 열릴 때 동기화를 계속 진행할 수 있어야 합니다.

가져오기 시점

앱이 새 데이터에 대한 알림을 받을 수 없으므로 다음 두 가지 시점에서 새 데이터를 확인하세요.

  • 앱이 포그라운드에서 활성화될 때마다 확인합니다. 이 경우에는 수명 주기 이벤트를 사용하세요.
  • 앱이 포그라운드에 남아 있는 동안 주기적으로 확인합니다. 새 데이터를 사용할 수 있게 되면 사용자가 화면을 업데이트하여 변경사항을 반영하도록 사용자에게 알림을 보내야 합니다.

비율 제한

드물지만 헬스 커넥트는 앱의 요청 비율을 제한합니다. 이는 배터리에 미치는 영향과 기기 성능을 제한하기 위해서입니다.

  • 비율 제한으로 인해 앱의 요청이 거부되지 않도록 권장사항 가이드라인을 따르는 것이 좋습니다.
  • 앱은 비율 제한에 대응할 수 있어야 합니다. 예를 들어 비율 제한으로 인해 요청이 실패하는 경우 다음 주기의 작업 중 백그라운드에 있는 데이터를 쓸 수 있습니다.

앱 온보딩

많은 앱에는 기능 교육 또는 사용자 동의 요청과 같은 맞춤 온보딩 흐름이 있습니다. 개발자는 사용자가 처음 앱과 상호작용할 때 헬스 커넥트가 시작하는 온보딩 활동을 내보내는 것이 좋습니다. 이를 위해 매니페스트에 다음을 추가하세요.

<!-- 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.ACTION_SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

이 기능 지원은 Android 14에서 아직 사용할 수 없지만 곧 지원될 예정입니다.

사용자가 앱을 헬스 커넥트에 연결하려고 하면 내보낸 활동이 실행됩니다. 이 활동은 다음 작업을 실행해야 합니다.

  • 쓰거나 읽은 데이터를 설명하는 등 관련 사용자 교육을 표시합니다.
  • 필요한 경우 사용자에게 동의를 요청합니다.
  • 헬스 커넥트에 권한을 요청합니다.
  • 주기적 worker를 예약하는 등 기타 애플리케이션별 로직을 실행합니다.
  • 완료되면 사용자가 활동을 닫을 수 있도록 합니다.

온보딩 활동을 내보내지 않는 앱의 경우 헬스 커넥트는 사용자가 앱을 연결하려고 하면 사용자를 대신 권한 관리 화면으로 안내합니다. 통합이 작동하기 위해 권한이 부여되기만 하면 되는 앱에는 이 방식이 적합할 수 있습니다.

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