메타데이터 요구사항

이 가이드는 헬스 커넥트 버전 1.2.0-alpha05 이상과 호환됩니다.

버전 1.1.0-alpha12 이상으로 업그레이드하는 개발자를 위해 헬스 커넥트의 메타데이터가 변경되었습니다.

라이브러리 정보

Google Maven Android Gradle 플러그인 아티팩트 ID는 업그레이드해야 하는 헬스 커넥트 라이브러리를 식별합니다. 모듈 수준 build.gradle 파일에 다음 헬스 커넥트 SDK 종속 항목을 추가합니다.

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

메타데이터 변경

생태계에 유용한 추가 메타데이터가 있는지 확인하는 데 도움이 되도록 버전 1.1.0-alpha12부터 헬스 커넥트 Jetpack SDK에 두 가지 메타데이터 변경사항이 도입되었습니다. metadata이 Record 생성자에 포함되지 않으면 생성자 내부 오류가 표시될 수 있습니다.

녹화 방법 지정

Record() 유형 객체가 인스턴스화될 때마다 메타데이터 세부정보를 지정해야 합니다.

헬스 커넥트에 데이터를 쓸 때는 Metadata를 인스턴스화하기 위해 해당하는 팩토리 메서드 중 하나를 사용하여 네 가지 기록 방법 중 하나를 지정해야 합니다.

예를 들면 다음과 같습니다.

 StepsRecord(
    startTime = Instant.ofEpochMilli(1234L),
    startZoneOffset = null,
    endTime = Instant.ofEpochMilli(1236L),
    endZoneOffset = null,
    metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH)),
    count = 10
)
HealthConnectManager.kt

기기 유형

자동으로 적극적으로 기록된 모든 데이터에 대해 기기 유형을 지정해야 합니다. 자세한 내용은 Jetpack 문서의 Device 클래스를 참고하세요. 현재 기기 유형에는 다음이 포함됩니다.

일부 Device.type 값은 최신 버전의 헬스 커넥트에서만 사용할 수 있습니다. 확장된 기기 유형 기능을 사용할 수 없는 경우 이러한 유형은 Device.TYPE_UNKNOWN로 처리됩니다.

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_EXTENDED_DEVICE_TYPES
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
} else {
  // Feature isn't available
}

예를 들면 다음과 같습니다.

 val WATCH_DEVICE = Device(
    manufacturer = "Google",
    model = "Pixel Watch",
    type = Device.TYPE_WATCH
)

// Phone
 val PHONE_DEVICE = Device(
    manufacturer = "Google",
    model = "Pixel 8",
    type = Device.TYPE_PHONE
)

// Ring
 val RING_DEVICE = Device(
    manufacturer = "Oura",
    model = "Ring Gen3",
    type = Device.TYPE_RING
)

// Scale
 val SCALE_DEVICE = Device(
    manufacturer = "Withings",
    model = "Body Comp",
    type = Device.TYPE_SCALE
)
HealthConnectManager.kt

고유 기기 식별자 (UDI)

Android 17 (API 수준 37.1) 또는 U 확장 프로그램 23 이상의 헬스 커넥트의 경우 Device 클래스에는 고유 기기 식별자 (UDI) 지원이 포함됩니다. 의료 기기의 등록된 UDI 모델 세부정보를 서면 기록과 연결하면 다운스트림 애플리케이션 (예: 원격 의료 플랫폼 또는 임상 포털)에서 임상 등급 판독값을 식별하고 일반 소비자용 웨어러블 데이터와 구분할 수 있습니다.

권한 선언

헬스 커넥트에 UDI 세부정보를 쓰려면 앱의 AndroidManifest.xml 파일에서 WRITE_DEVICE_UDI 권한을 선언해야 합니다.

<uses-permission android:name="android.permission.health.WRITE_DEVICE_UDI" />

WRITE_DEVICE_UDI은 일반 권한입니다. 매니페스트에서 선언해야 하지만 런타임에 사용자에게 요청할 필요는 없습니다. 설치 시 앱에 자동으로 부여됩니다.

기기 식별자 (DI) 부분만 작성

전체 UDI에는 다음 두 부분이 포함됩니다.

• 기기 식별자 (UDI-DI): 발급 기관 (예: GS1)에서 특정 기기 모델에 할당한 전 세계적으로 인정되는 식별자입니다.
• 생산 식별자 (UDI-PI): 일련번호, 배치 번호, 제조일, 만료일과 같은 단위별 속성입니다.

사용자 개인 정보를 보호하려면 헬스 커넥트에서 코드의 UDI-DI 부분만 채우세요. 생산 식별자 속성 (예: 일련번호 또는 배치 번호)은 포함하지 마세요.

코드 예

참고: Device 인스턴스를 생성할 때 UDI를 설정할 수 있습니다.

val device = Device(
    type = Device.TYPE_CONSUMER_MEDICAL_DEVICE,
    manufacturer = "Omron",
    model = "HEM-7121",
    udi = "04015674011832" // Device Identifier (UDI-DI) portion only
)

val device = Device.Builder()
    .setType(Device.DEVICE_TYPE_CONSUMER_MEDICAL_DEVICE)
    .setManufacturer("Omron")
    .setModel("HEM-7121")
    .setUdi("04015674011832") // Device Identifier (UDI-DI) portion only
    .build()

WRITE_DEVICE_UDI 권한을 선언하지 않고 UDI로 데이터를 쓰면 헬스 커넥트에서 쓰기 시간에 SecurityException를 발생시킵니다.

UDI를 사용하여 기기 승인 확인

헬스 커넥트는 전송 계층 역할을 하며 UDI의 진위성 또는 등록 상태를 검증하지 않습니다.

데이터 리더의 경우 UDI가 있으면 데이터가 등록된 의료 기기에서 비롯된 것임을 나타냅니다. 읽기 앱은 FDA의 전역 고유 기기 식별 데이터베이스 (GUDID) 또는 EU의 EUDAMED와 같은 규제 데이터베이스를 쿼리하여 기기 분류, 규제 승인 상태 (예: 클래스 I, II 또는 III) 또는 특정 용도를 확인해야 합니다.

스니펫 업데이트됨

새 메타데이터 요구사항을 준수하기 위해 새 스니펫이 필요한 경우 헬스 커넥트 가이드가 업데이트되었습니다. 몇 가지 예는 데이터 쓰기 페이지를 참고하세요.

새 메타데이터 메서드

메타데이터를 더 이상 직접 인스턴스화할 수 없으므로 팩토리 메서드 중 하나를 사용하여 새 메타데이터 인스턴스를 가져오세요. 팩토리 메서드는 기기 또는 센서를 사용하여 데이터를 기록할 때 기기 정보가 제공되었는지 확인합니다. 수동으로 입력한 데이터의 경우 기기 정보 제공은 선택사항입니다. 각 함수에는 세 가지 서명 변형이 있습니다.

• activelyRecorded

  • fun activelyRecorded(device: Device): Metadata.
  • fun activelyRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
  • fun activelyRecordedWithId(id: String, device: Device): Metadata

• autoRecorded

  • fun autoRecorded(device: Device): Metadata
  • fun autoRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
  • fun autoRecordedWithId(id: String, device: Device): Metadata

• manualEntry

  • fun manualEntry(device: Device? = null): Metadata
  • fun manualEntry(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
  • fun manualEntryWithId(id: String, device: Device? = null): Metadata

• unknownRecordingMethod

  • fun unknownRecordingMethod(device: Device? = null): Metadata
  • fun unknownRecordingMethod(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
  • fun unknownRecordingMethodWithId(id: String, device: Device? = null): Metadata

자세한 내용은 Android 오픈소스 프로젝트를 참고하세요.

테스트 데이터

테스트 라이브러리와 MetadataTestHelper를 사용하여 예상 메타데이터 값을 모의합니다.

private val TEST_METADATA =
    Metadata.unknownRecordingMethod(
        clientRecordId = "clientId",
        clientRecordVersion = 1L,
        device = Device(type = Device.TYPE_UNKNOWN),
    ).populatedWithTestValues(id = "test")

이는 레코드 삽입 중에 이러한 값을 자동으로 채우는 헬스 커넥트 구현의 동작을 시뮬레이션합니다.

테스트 라이브러리의 경우 모듈 수준 build.gradle 파일에 다음 헬스 커넥트 SDK 종속 항목을 추가해야 합니다.

dependencies {
  testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}

라이브러리 업그레이드

수행해야 하는 주요 단계는 다음과 같습니다.

1. 라이브러리를 1.1.0-alpha12로 업그레이드합니다.

2. 라이브러리를 빌드할 때 새 메타데이터가 필요한 경우 컴파일 오류가 발생합니다. 이 오류를 해결하고 이전을 완료하려면 다음 변경사항을 적용해야 합니다.

   • Record를 구성할 때는 녹화 방법을 지정해야 합니다. 이는 Metadata에 제공된 팩토리 메서드(예: Metadata.manualEntry() 또는 Metadata.activelyRecorded(device = Device(...))) 중 하나를 사용하여 실행됩니다.
   • 기기에서 기록한 데이터의 경우 Device.TYPE_WATCH 또는 Device.TYPE_PHONE과 같은 기기 유형을 지정해야 합니다.

3. 앱이 확장 기기 유형을 쓰는 경우 기능이 제공되지 않는 기기에서 예기치 않은 TYPE_UNKNOWN를 방지하기 위해 FEATURE_EXTENTED_DEVICE_TYPES 뒤에 게이트합니다.