이 가이드는 헬스 커넥트 버전 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를 인스턴스화함으로써 네 가지 기록 방법 중 하나를 지정해야 합니다.
| 기록 방법 | 설명 |
|---|---|
RECORDING_METHOD_UNKNOWN |
녹음 방법을 확인할 수 없습니다. |
RECORDING_METHOD_MANUAL_ENTRY |
사용자가 데이터를 입력했습니다. |
RECORDING_METHOD_AUTOMATICALLY_RECORDED |
기기 또는 센서가 데이터를 기록했습니다. |
RECORDING_METHOD_ACTIVELY_RECORDED |
사용자가 기기에서 녹화 세션의 시작 또는 종료를 시작했습니다. |
예를 들면 다음과 같습니다.
StepsRecord( startTime = Instant.ofEpochMilli(1234L), startZoneOffset = null, endTime = Instant.ofEpochMilli(1236L), endZoneOffset = null, metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH)), count = 10 )
기기 유형
자동으로 적극적으로 기록되는 모든 데이터에 기기 유형을 지정해야 합니다. 자세한 내용은 Jetpack 문서의 Device 클래스를 참고하세요. 현재 기기 유형은 다음과 같습니다.
| 기기 유형 | 설명 |
|---|---|
TYPE_UNKNOWN |
기기 유형을 알 수 없습니다. |
TYPE_WATCH |
기기 유형은 시계입니다. |
TYPE_PHONE |
기기 유형은 휴대전화입니다. |
TYPE_SCALE |
기기 유형은 체중계입니다. |
TYPE_RING |
기기 유형은 반지입니다. |
TYPE_HEAD_MOUNTED |
기기 유형은 헤드 마운트 기기입니다. |
TYPE_FITNESS_BAND |
기기 유형은 피트니스 밴드입니다. |
TYPE_CHEST_STRAP |
기기 유형은 가슴 스트랩입니다. |
TYPE_SMART_DISPLAY |
기기 유형은 스마트 디스플레이입니다. |
일부 Device.type 값은 최신 버전의 헬스 커넥트에서만 사용할 수 있습니다. 확장된 기기 유형 기능을 사용할 수 없는 경우 이러한 유형은 Device.TYPE_UNKNOWN로 처리됩니다.
| 확장된 기기 유형 | 설명 |
|---|---|
TYPE_CONSUMER_MEDICAL_DEVICE |
기기 유형은 의료 기기입니다. |
TYPE_GLASSES |
기기 유형이 스마트 글라스 또는 안경입니다. |
TYPE_HEARABLE |
기기 유형은 히어러블 기기입니다. |
TYPE_FITNESS_MACHINE |
기기 유형은 고정형 기기입니다. |
TYPE_FITNESS_EQUIPMENT |
기기 유형은 운동 기구입니다. |
TYPE_PORTABLE_COMPUTER |
기기 유형은 휴대용 컴퓨터입니다. |
TYPE_METER |
기기 유형은 측정 미터입니다. |
FEATURE_EXTENDED_DEVICE_TYPES의 사용 가능 여부를 확인하세요.
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 )
고유 기기 식별자 (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를 설정할 수 있습니다.
Jetpack SDK
val device = Device( type = Device.TYPE_CONSUMER_MEDICAL_DEVICE, manufacturer = "Omron", model = "HEM-7121", udi = "04015674011832" // Device Identifier (UDI-DI) portion only )
Platform API
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 (Global Unique Device Identification Database) 또는 EU의 EUDAMED와 같은 규제 데이터베이스를 쿼리하여 기기 분류, 규제 승인 상태 (예: 클래스 I, II, III) 또는 특정 용도를 확인해야 합니다.
스니펫이 업데이트됨
새로운 메타데이터 요구사항을 준수하기 위해 새로운 스니펫이 필요한 경우 헬스 커넥트 가이드가 업데이트되었습니다. 몇 가지 예시는 데이터 쓰기 페이지를 참고하세요.
새 메타데이터 메서드
메타데이터를 더 이상 직접 인스턴스화할 수 없으므로 팩토리 메서드 중 하나를 사용하여 메타데이터의 새 인스턴스를 가져옵니다. 팩토리 메서드는 기기 또는 센서를 사용하여 데이터를 기록할 때 기기 정보가 제공되는지 확인합니다. 수동으로 입력한 데이터의 경우 기기 정보를 제공하는 것은 선택사항입니다. 각 함수에는 세 가지 서명 변형이 있습니다.
activelyRecordedfun activelyRecorded(device: Device): Metadata.fun activelyRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadatafun activelyRecordedWithId(id: String, device: Device): Metadata
autoRecordedfun autoRecorded(device: Device): Metadatafun autoRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadatafun autoRecordedWithId(id: String, device: Device): Metadata
manualEntryfun manualEntry(device: Device? = null): Metadatafun manualEntry(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadatafun manualEntryWithId(id: String, device: Device? = null): Metadata
unknownRecordingMethodfun unknownRecordingMethod(device: Device? = null): Metadatafun unknownRecordingMethod(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadatafun 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")
이는 레코드 삽입 중에 이러한 값을 자동으로 채우는 헬스 커넥트 구현의 동작을 시뮬레이션합니다.
테스트 라이브러리의 경우 이 헬스 커넥트 SDK 종속 항목을 모듈 수준 build.gradle 파일에 추가해야 합니다.
dependencies {
testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}
라이브러리 업그레이드
수행해야 하는 주요 단계는 다음과 같습니다.
라이브러리를 1.1.0-alpha12로 업그레이드합니다.
라이브러리를 빌드할 때 새 메타데이터가 필요한 경우 컴파일 오류가 발생합니다. 이러한 오류를 해결하고 이전을 완료하려면 다음 변경사항을 확인하세요.
Record를 구성할 때는 녹음 방법을 지정해야 합니다. 이는Metadata에서 제공하는 팩토리 메서드 중 하나(예:Metadata.manualEntry()또는Metadata.activelyRecorded(device = Device(...)))를 사용하여 실행됩니다.- 기기에서 기록한 데이터의 경우
Device.TYPE_WATCH또는Device.TYPE_PHONE과 같은 기기 유형을 지정해야 합니다.
앱에서 확장된 기기 유형을 작성하는 경우 기능이 제공되지 않는 기기에서 예기치 않은
TYPE_UNKNOWN가 발생하지 않도록FEATURE_EXTENTED_DEVICE_TYPES뒤에 게이트를 지정합니다.