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

คู่มือนี้ใช้ได้กับ Health Connect เวอร์ชัน 1.2.0-alpha05 ขึ้นไป

มีการเปลี่ยนแปลงข้อมูลเมตาใน Health Connect สำหรับ นักพัฒนาแอปที่อัปเกรดเป็นรุ่น 1.1.0-alpha12 หรือใหม่กว่า

ข้อมูลห้องสมุด

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

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

การเปลี่ยนแปลงข้อมูลเมตา

เราได้ทำการเปลี่ยนแปลงข้อมูลเมตา 2 รายการใน Jetpack SDK สำหรับ Health Connect ตั้งแต่เวอร์ชัน 1.1.0-alpha12 เพื่อช่วยยืนยันว่ามีข้อมูลเมตาเพิ่มเติมที่เป็นประโยชน์ อยู่ในระบบนิเวศ หากไม่ได้รวม metadata ไว้ในตัวสร้างของ Record คุณอาจเห็นข้อผิดพลาด Constructor internal

ระบุวิธีการบันทึก

คุณต้องระบุรายละเอียดข้อมูลเมตาทุกครั้งที่สร้างอินสแตนซ์ของRecord()ออบเจ็กต์ประเภท

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

ประเภทอุปกรณ์

คุณต้องระบุประเภทอุปกรณ์สำหรับข้อมูลทั้งหมดที่บันทึกโดยอัตโนมัติและที่บันทึกอย่างต่อเนื่อง ดูรายละเอียดเพิ่มเติมได้ใน คลาส Device ในเอกสารประกอบของ Jetpack ประเภทอุปกรณ์ปัจจุบัน มีดังนี้

ค่า Device.type บางค่าใช้ได้เฉพาะใน Health Connect เวอร์ชันที่ใหม่กว่า เมื่อฟีเจอร์ประเภทอุปกรณ์แบบขยายไม่พร้อมใช้งาน ระบบจะถือว่าประเภทเหล่านี้เป็น 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)

สำหรับ Health Connect ใน Android 17 (API ระดับ 37.1) หรือ U Extension 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

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()

หากคุณเขียนข้อมูลด้วย UDI โดยไม่ประกาศสิทธิ์ WRITE_DEVICE_UDI Health Connect จะแสดง SecurityException ในเวลาที่เขียน

ใช้ UDI เพื่อยืนยันการล้างข้อมูลอุปกรณ์

Health Connect ทำหน้าที่เป็นเลเยอร์การรับส่งและไม่ตรวจสอบความถูกต้องหรือสถานะการจดทะเบียนของ UDI

สำหรับผู้อ่านข้อมูล การมี UDI แสดงว่าข้อมูลมาจากอุปกรณ์ทางการแพทย์ที่ลงทะเบียน แอปอ่านควรค้นหาฐานข้อมูลด้านกฎระเบียบ เช่น ฐานข้อมูลการระบุอุปกรณ์ที่ไม่ซ้ำกันทั่วโลก (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 ของ Health Connect SDK นี้ลงในไฟล์ 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 ที่ไม่คาดคิดในอุปกรณ์ ที่ฟีเจอร์ไม่พร้อมใช้งาน