คู่มือนี้ใช้ได้กับ Health Connect เวอร์ชัน 1.2.0-alpha05 ขึ้นไป
มีการเปลี่ยนแปลงข้อมูลเมตาใน Health Connect สำหรับนักพัฒนาแอปที่อัปเกรดเป็นรุ่น 1.1.0-alpha12 ขึ้นไป
ข้อมูลห้องสมุด
รหัสอาร์ติแฟกต์ปลั๊กอิน Android Gradle ของ Google Maven จะระบุไลบรารี Health Connect ที่คุณจะต้องอัปเกรด
เพิ่มทรัพยากร Dependency ของ SDK สำหรับ Health Connect นี้ลงในไฟล์ build.gradle ระดับโมดูล
dependencies {
implementation "androidx.health.connect:connect-client:1.1.0-alpha12"
}
การเปลี่ยนแปลงข้อมูลเมตา
มีการเปลี่ยนแปลงข้อมูลเมตา 2 รายการใน Health Connect Jetpack SDK ตั้งแต่เวอร์ชัน 1.1.0-alpha12 เพื่อช่วยยืนยันว่ามีข้อมูลเมตาที่เป็นประโยชน์เพิ่มเติมในระบบนิเวศ หากไม่ได้รวม metadata ไว้ในคอนสตรัคเตอร์ Record คุณอาจเห็นข้อผิดพลาด Constructor internal
ระบุวิธีการบันทึก
คุณต้องระบุรายละเอียดข้อมูลเมตาทุกครั้งที่มีการสร้างอินสแตนซ์ออบเจ็กต์ประเภท Record()
เมื่อเขียนข้อมูลลงใน Health Connect คุณต้องระบุวิธีการบันทึก 1 ใน 4 วิธีโดยใช้เมธอด Factory ที่เกี่ยวข้องเพื่อสร้างอินสแตนซ์ 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 )
ประเภทอุปกรณ์
คุณต้องระบุประเภทอุปกรณ์สำหรับข้อมูลทั้งหมดที่บันทึกโดยอัตโนมัติและบันทึกอย่างต่อเนื่อง ดูรายละเอียดเพิ่มเติมได้ที่คลาส Device ในเอกสารประกอบของ Jetpack ประเภทอุปกรณ์ปัจจุบันมีดังนี้
| ประเภทอุปกรณ์ | คำอธิบาย |
|---|---|
TYPE_UNKNOWN |
ไม่รู้จักประเภทอุปกรณ์ |
TYPE_WATCH |
ประเภทอุปกรณ์คือนาฬิกา |
TYPE_PHONE |
ประเภทอุปกรณ์คือโทรศัพท์ |
TYPE_SCALE |
ประเภทอุปกรณ์คือเครื่องชั่งน้ำหนัก |
TYPE_RING |
ประเภทอุปกรณ์คือแหวน |
TYPE_HEAD_MOUNTED |
ประเภทอุปกรณ์คืออุปกรณ์ที่ติดตั้งบนศีรษะ |
TYPE_FITNESS_BAND |
ประเภทอุปกรณ์คือสายรัดข้อมือเพื่อสุขภาพ |
TYPE_CHEST_STRAP |
ประเภทอุปกรณ์คือสายคาดอก |
TYPE_SMART_DISPLAY |
ประเภทอุปกรณ์คือจออัจฉริยะ |
ค่า Device.type บางค่าใช้ได้เฉพาะใน Health Connect เวอร์ชันที่ใหม่กว่าเท่านั้น เมื่อฟีเจอร์ประเภทอุปกรณ์เพิ่มเติมไม่พร้อมใช้งาน ระบบจะถือว่าประเภทเหล่านี้เป็น 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)
สำหรับ Health Connect ใน Android 17 (ระดับ API 37.1) หรือส่วนขยาย U เวอร์ชัน 23 ขึ้นไป คลาส Device จะรองรับตัวระบุอุปกรณ์ที่ไม่ซ้ำกัน (UDI) การเชื่อมโยงรายละเอียดโมเดล UDI ที่ลงทะเบียนของอุปกรณ์ทางการแพทย์กับบันทึกที่คุณเขียนจะช่วยให้แอปพลิเคชันปลายทาง (เช่น แพลตฟอร์มการสาธารณสุขทางไกลหรือพอร์ทัลทางคลินิก) สามารถระบุค่าที่อ่านได้ในระดับคลินิกและแยกค่าดังกล่าวออกจากข้อมูลอุปกรณ์ที่สวมใส่ได้สำหรับผู้บริโภคทั่วไป
ประกาศสิทธิ์
หากต้องการเขียนรายละเอียด UDI ลงใน Health Connect คุณต้องประกาศสิทธิ์ WRITE_DEVICE_UDI ในไฟล์ AndroidManifest.xml ของแอป ดังนี้
<uses-permission android:name="android.permission.health.WRITE_DEVICE_UDI" />
โปรดทราบว่า WRITE_DEVICE_UDI เป็นสิทธิ์ปกติ คุณต้องประกาศสิทธิ์นี้ในไฟล์ Manifest แต่ไม่จำเป็นต้องขอสิทธิ์จากผู้ใช้ที่รันไทม์ ระบบจะให้สิทธิ์นี้แก่แอปโดยอัตโนมัติเมื่อติดตั้ง
เขียนเฉพาะส่วนตัวระบุอุปกรณ์ (DI)
UDI ที่สมบูรณ์ประกอบด้วย 2 ส่วน ได้แก่
- ตัวระบุอุปกรณ์ (UDI-DI): ตัวระบุที่ได้รับการยอมรับทั่วโลกซึ่งหน่วยงานที่ออก (เช่น GS1) กำหนดให้กับรุ่นอุปกรณ์ที่เฉพาะเจาะจง
- ตัวระบุการผลิต (UDI-PI): แอตทริบิวต์เฉพาะหน่วย เช่น หมายเลขซีเรียล หมายเลขชุด วันที่ผลิต หรือวันที่หมดอายุ
เพื่อปกป้องความเป็นส่วนตัวของผู้ใช้ ให้ป้อนเฉพาะส่วน UDI-DI ของรหัสใน Health Connect อย่าใส่แอตทริบิวต์ตัวระบุสินค้า (เช่น หมายเลขซีเรียลหรือหมายเลขชุด)
ตัวอย่างโค้ด
หมายเหตุ: คุณสามารถตั้งค่า UDI ได้เมื่อสร้างอินสแตนซ์ Device
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()
หากคุณเขียนข้อมูลที่มี UDI โดยไม่ประกาศสิทธิ์ WRITE_DEVICE_UDI Health Connect จะแสดง SecurityException ณ เวลาที่เขียน
ใช้ UDI เพื่อยืนยันการผ่านการรับรองของอุปกรณ์
Health Connect ทำหน้าที่เป็นเลเยอร์การรับส่งข้อมูลและไม่ได้ตรวจสอบความถูกต้องหรือสถานะการลงทะเบียนของ UDI
สำหรับเครื่องอ่านข้อมูล การมี UDI บ่งชี้ว่าข้อมูลมาจากอุปกรณ์ทางการแพทย์ที่จดทะเบียน แอปอ่านค่าควรค้นหาฐานข้อมูลด้านกฎระเบียบ เช่น Global Unique Device Identification Database (GUDID) ของ FDA หรือ EUDAMED ของสหภาพยุโรป เพื่อยืนยันการจัดประเภทอุปกรณ์ สถานะการรับรองตามกฎระเบียบ (เช่น คลาส I, II หรือ III) หรือวัตถุประสงค์การใช้งานที่เฉพาะเจาะจง
อัปเดตตัวอย่างข้อมูลแล้ว
เราได้อัปเดตคู่มือ Health Connect ในทุกที่ที่จำเป็นต้องใช้ข้อมูลโค้ดใหม่เพื่อให้เป็นไปตามข้อกำหนดด้านข้อมูลเมตาใหม่ ดูตัวอย่างได้ที่หน้าเขียนข้อมูล
เมธอดข้อมูลเมตาใหม่
คุณไม่สามารถสร้างอินสแตนซ์ข้อมูลเมตาได้โดยตรงอีกต่อไป ดังนั้นให้ใช้เมธอด Factory อย่างใดอย่างหนึ่งเพื่อรับอินสแตนซ์ใหม่ของข้อมูลเมตา เมธอด Factory จะตรวจสอบว่ามีการระบุข้อมูลอุปกรณ์เมื่อมีการใช้อุปกรณ์หรือเซ็นเซอร์เพื่อบันทึกข้อมูล สำหรับข้อมูลที่ป้อนด้วยตนเอง การระบุข้อมูลอุปกรณ์ยังคงเป็นตัวเลือกที่ไม่บังคับ แต่ละฟังก์ชันมีตัวแปรซิกเนเจอร์ 3 แบบ ดังนี้
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")
ซึ่งจะจำลองลักษณะการทำงานของการติดตั้งใช้งาน Health Connect ที่จะป้อนค่าเหล่านี้โดยอัตโนมัติระหว่างการแทรกระเบียน
สำหรับไลบรารีการทดสอบ คุณต้องเพิ่มทรัพยากร Dependency ของ SDK สำหรับ Health Connect นี้ลงในไฟล์ build.gradle ระดับโมดูล
dependencies {
testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}
อัปเกรดไลบรารี
ขั้นตอนหลักที่คุณต้องดำเนินการมีดังนี้
อัปเกรดไลบรารีเป็น 1.1.0-alpha12
เมื่อสร้างไลบรารี ระบบจะแสดงข้อผิดพลาดในการคอมไพล์เมื่อจำเป็นต้องใช้ข้อมูลเมตาใหม่ หากต้องการแก้ไขข้อผิดพลาดเหล่านี้และทำการย้ายข้อมูลให้เสร็จสมบูรณ์ ให้ตรวจสอบว่าคุณได้ทำการเปลี่ยนแปลงต่อไปนี้
- คุณต้องระบุวิธีการบันทึกเมื่อสร้าง
Recordซึ่งทำได้โดยใช้เมธอด Factory เมธอดใดเมธอดหนึ่งที่มีให้ในMetadataเช่นMetadata.manualEntry()หรือMetadata.activelyRecorded(device = Device(...)) - สำหรับข้อมูลที่บันทึกโดยอุปกรณ์ คุณต้องระบุประเภทอุปกรณ์ เช่น
Device.TYPE_WATCHหรือDevice.TYPE_PHONE
- คุณต้องระบุวิธีการบันทึกเมื่อสร้าง
หากแอปของคุณเขียนประเภทอุปกรณ์แบบขยาย ให้จำกัดประเภทอุปกรณ์เหล่านั้นไว้หลัง
FEATURE_EXTENTED_DEVICE_TYPESเพื่อหลีกเลี่ยงTYPE_UNKNOWNที่ไม่คาดคิดในอุปกรณ์ที่ไม่มีฟีเจอร์นี้