ข้อกำหนดข้อมูลเมตา

คู่มือนี้ใช้ได้กับ 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 ประเภทอุปกรณ์คือมิเตอร์วัดค่า
หากต้องการตรวจสอบว่าอุปกรณ์ของผู้ใช้รองรับประเภทอุปกรณ์เพิ่มเติมใน Health Connect หรือไม่ ให้ตรวจสอบความพร้อมใช้งานของ 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 แบบ ดังนี้

  • 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")

ซึ่งจะจำลองลักษณะการทำงานของการติดตั้งใช้งาน Health Connect ที่จะป้อนค่าเหล่านี้โดยอัตโนมัติระหว่างการแทรกระเบียน

สำหรับไลบรารีการทดสอบ คุณต้องเพิ่มทรัพยากร Dependency ของ SDK สำหรับ Health Connect นี้ลงในไฟล์ build.gradle ระดับโมดูล

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

อัปเกรดไลบรารี

ขั้นตอนหลักที่คุณต้องดำเนินการมีดังนี้

  1. อัปเกรดไลบรารีเป็น 1.1.0-alpha12

  2. เมื่อสร้างไลบรารี ระบบจะแสดงข้อผิดพลาดในการคอมไพล์เมื่อจำเป็นต้องใช้ข้อมูลเมตาใหม่ หากต้องการแก้ไขข้อผิดพลาดเหล่านี้และทำการย้ายข้อมูลให้เสร็จสมบูรณ์ ให้ตรวจสอบว่าคุณได้ทำการเปลี่ยนแปลงต่อไปนี้

    • คุณต้องระบุวิธีการบันทึกเมื่อสร้าง Record ซึ่งทำได้โดยใช้เมธอด Factory เมธอดใดเมธอดหนึ่งที่มีให้ใน Metadata เช่น Metadata.manualEntry() หรือ Metadata.activelyRecorded(device = Device(...))
    • สำหรับข้อมูลที่บันทึกโดยอุปกรณ์ คุณต้องระบุประเภทอุปกรณ์ เช่น Device.TYPE_WATCH หรือ Device.TYPE_PHONE
  3. หากแอปของคุณเขียนประเภทอุปกรณ์แบบขยาย ให้จำกัดประเภทอุปกรณ์เหล่านั้นไว้หลัง FEATURE_EXTENTED_DEVICE_TYPES เพื่อหลีกเลี่ยง TYPE_UNKNOWN ที่ไม่คาดคิดในอุปกรณ์ที่ไม่มีฟีเจอร์นี้