พัฒนาประสบการณ์การใช้งานข้อมูลสำคัญด้วย Health Connect

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

หากต้องการสร้างแอปที่จัดการสัญญาณชีพของผู้ใช้ คุณสามารถใช้ Health Connect เพื่อทำสิ่งต่างๆ ต่อไปนี้ได้

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

คู่มือนี้อธิบายวิธีทำงานกับประเภทข้อมูลสัญญาณชีพ ซึ่งครอบคลุมสิทธิ์ เวิร์กโฟลว์การอ่านและเขียน และแนวทางปฏิบัติแนะนำ

ภาพรวม: การสร้างเครื่องมือติดตามสัญญาณชีพที่ครอบคลุม

คุณสร้างประสบการณ์การติดตามสัญญาณชีพที่ครอบคลุมได้โดยใช้ Health Connect โดยทำตามขั้นตอนหลักต่อไปนี้

  • การขอสิทธิ์ที่เหมาะสมสำหรับประเภทข้อมูลสัญญาณชีพ
  • การเขียนข้อมูลสัญญาณชีพโดยใช้บันทึก เช่น BloodPressureRecord, HeartRateRecord และบันทึกสัญญาณชีพอื่นๆ
  • การอ่านข้อมูลสัญญาณชีพเพื่อแสดงผล วิเคราะห์ หรือซิงค์
  • การใช้การจัดกลุ่มเพื่อเขียนและอ่านข้อมูลอย่างมีประสิทธิภาพ

เวิร์กโฟลว์นี้ช่วยให้ทำงานร่วมกับแอป Health Connect อื่นๆ ได้และยืนยันการเข้าถึงข้อมูลที่ผู้ใช้ควบคุม

ก่อนเริ่มต้น

สิ่งที่ควรทำก่อนใช้ฟีเจอร์ Vitals

แนวคิดสำคัญ

ข้อมูลสัญญาณชีพใน Health Connect จะแสดงด้วยประเภทบันทึกต่างๆ ซึ่งแต่ละประเภทจะสอดคล้องกับการวัดทางสรีรวิทยาที่เฉพาะเจาะจง ข้อมูลสัญญาณชีพมักจะบันทึกเป็นข้อมูล ณ จุดเวลาหนึ่งหรือตามช่วงเวลา ซึ่งต่างจากเซสชันการออกกำลังกาย

ประเภทข้อมูลสัญญาณชีพ

ข้อมูลสัญญาณชีพจะแสดงตามประเภทระเบียนแต่ละประเภท ประเภทที่พบบ่อยมีดังนี้

  • BloodPressureRecord: แสดงค่าความดันโลหิตที่อ่านได้ 1 ค่า ซึ่งรวมถึงความดันขณะหัวใจบีบตัวและคลายตัว และตำแหน่งของร่างกาย
  • HeartRateRecord: แสดงชุดการวัดอัตราการเต้นของหัวใจ
  • RestingHeartRateRecord: แสดงการวัดอัตราการเต้นของหัวใจขณะพัก 1 ครั้ง
  • BodyTemperatureRecord: แสดงค่าอุณหภูมิของร่างกายที่อ่านได้ 1 ค่า รวมถึงตำแหน่งที่วัด
  • BloodGlucoseRecord: แสดงค่าระดับน้ำตาลกลูโคสในเลือดค่าเดียว รวมถึงความสัมพันธ์กับมื้ออาหารและแหล่งที่มาของตัวอย่าง
  • OxygenSaturationRecord: แสดงค่าความอิ่มตัวของออกซิเจนในเลือดที่อ่านได้ 1 ค่า
  • RespiratoryRateRecord: แสดงการวัดอัตราการหายใจ 1 ครั้ง

ดูรายการประเภทข้อมูลทั้งหมดได้ที่ประเภทข้อมูลของ Health Connect

ข้อควรพิจารณาในการพัฒนา

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

สิทธิ์

แอปของคุณต้องขอสิทธิ์ Health Connect ที่เกี่ยวข้องก่อนอ่านหรือเขียนข้อมูลสัญญาณชีพ สิทธิ์ทั่วไปสำหรับค่าสัญญาณชีพ ได้แก่ ความดันโลหิต อัตราการเต้นของหัวใจ อุณหภูมิร่างกาย น้ำตาลกลูโคสในเลือด ความอิ่มตัวของออกซิเจน และอัตราการหายใจ ซึ่งรวมถึงสิ่งต่อไปนี้

  • ความดันโลหิต: สิทธิ์อ่านและเขียนสำหรับ BloodPressureRecord
  • อัตราการเต้นของหัวใจ: สิทธิ์อ่านและเขียนสำหรับ HeartRateRecord
  • อัตราการเต้นของหัวใจขณะพัก: สิทธิ์อ่านและสิทธิ์เขียนสำหรับ RestingHeartRateRecord
  • อุณหภูมิร่างกาย: สิทธิ์อ่านและเขียนสำหรับ BodyTemperatureRecord
  • น้ำตาลกลูโคสในเลือด: สิทธิ์อ่านและสิทธิ์เขียนสำหรับ BloodGlucoseRecord
  • ความอิ่มตัวของออกซิเจน: สิทธิ์อ่านและสิทธิ์เขียนสำหรับ OxygenSaturationRecord
  • อัตราการหายใจ: สิทธิ์อ่านและสิทธิ์เขียนสำหรับ RespiratoryRateRecord

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

หลังจากสร้างอินสแตนซ์ไคลเอ็นต์แล้ว แอปของคุณจะต้องขอสิทธิ์จากผู้ใช้ ผู้ใช้ต้องได้รับอนุญาตให้ให้สิทธิ์หรือปฏิเสธสิทธิ์ได้ทุกเมื่อ โดยสร้างชุดสิทธิ์สำหรับประเภทข้อมูลที่จำเป็น ตรวจสอบว่าได้ประกาศสิทธิ์ในชุดสิทธิ์ในไฟล์ Manifest ของ Android ก่อน

val permissions =
    setOf(
        HealthPermission.getReadPermission(BloodPressureRecord::class),
        HealthPermission.getWritePermission(BloodPressureRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(BodyTemperatureRecord::class),
        HealthPermission.getWritePermission(BodyTemperatureRecord::class)
    )
ใช้ getGrantedPermissions เพื่อดูว่าแอปของคุณได้รับสิทธิ์ที่จำเป็นแล้วหรือยัง หากไม่มี ให้ใช้ createRequestPermissionResultContract เพื่อขอสิทธิ์เหล่านั้น หน้าจอแสดงสิทธิ์ของ Health Connect จะปรากฏขึ้น
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
เนื่องจากผู้ใช้สามารถให้หรือเพิกถอนสิทธิ์ได้ทุกเมื่อ แอปของคุณจึงต้องตรวจสอบสิทธิ์ทุกครั้งก่อนใช้งานและจัดการสถานการณ์ที่สิทธิ์หายไป

หากต้องการขอสิทธิ์ ให้เรียกใช้ฟังก์ชัน checkPermissionsAndRun ดังนี้

if (!granted.containsAll(permissions)) {
    // Check if required permissions are not granted, and return
    return emptySet()
}
// Permissions already granted; proceed with inserting or reading data

หากต้องการขอสิทธิ์สำหรับข้อมูลประเภทเดียวเท่านั้น เช่น ความดันโลหิต ให้ระบุเฉพาะข้อมูลประเภทนั้นในกลุ่มสิทธิ์ ดังนี้

การเข้าถึงความดันโลหิตได้รับการปกป้องโดยสิทธิ์ต่อไปนี้

  • android.permission.health.READ_BLOOD_PRESSURE
  • android.permission.health.WRITE_BLOOD_PRESSURE

หากต้องการเพิ่มความสามารถในการวัดความดันโลหิตลงในแอป ให้เริ่มด้วยการขอสิทธิ์สำหรับประเภทข้อมูล BloodPressureRecord

สิทธิ์ที่คุณต้องประกาศเพื่อให้สามารถเขียนข้อมูลความดันโลหิตได้มีดังนี้

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

หากต้องการอ่านความดันโลหิต คุณต้องขอสิทธิ์ต่อไปนี้

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

เขียนข้อมูลสัญญาณชีพ

ส่วนนี้จะอธิบายวิธีเขียนข้อมูลสัญญาณชีพลงใน Health Connect โดยปกติแล้ว ข้อมูลสัญญาณชีพจะเขียนเป็นบันทึกแต่ละรายการ หากคุณเขียนข้อมูลหลายรายการพร้อมกัน เช่น การซิงค์จากเซ็นเซอร์หรือแบ็กเอนด์ ให้ใช้การจัดกลุ่ม

ตัวอย่างการเขียน BloodPressureRecord:

suspend fun writeBloodPressureRecord(healthConnectClient: HealthConnectClient) {
    val record = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    healthConnectClient.insertRecords(listOf(record))
}

การเขียนเป็นกลุ่ม

หากแอปของคุณต้องการเขียนจุดข้อมูลหลายจุด เช่น การซิงค์ข้อมูลจากอุปกรณ์ที่เชื่อมต่อหรือบริการแบ็กเอนด์ คุณควรเขียนแบบกลุ่มเพื่อปรับปรุงประสิทธิภาพและลดการใช้แบตเตอรี่ Health Connect สามารถจัดการบันทึกได้สูงสุด 1,000 รายการในคำขอเขียนรายการเดียว

โค้ดต่อไปนี้แสดงวิธีเขียนหลายระเบียนพร้อมกันแบบเป็นกลุ่ม

suspend fun writeBatchRecords(healthConnectClient: HealthConnectClient) {
    val bloodPressureRecord = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    val heartRateRecord = HeartRateRecord(
        startTime = Instant.now().minusSeconds(60),
        startZoneOffset = ZoneOffset.UTC,
        endTime = Instant.now(),
        endZoneOffset = ZoneOffset.UTC,
        samples = listOf(HeartRateRecord.Sample(time = Instant.now().minusSeconds(30), beatsPerMinute = 80))
    )
    healthConnectClient.insertRecords(listOf(bloodPressureRecord, heartRateRecord))
}

กำลังอ่านข้อมูลสัญญาณชีพ

แอปสามารถอ่านข้อมูลสัญญาณชีพเพื่อแสดงการวัด วิเคราะห์แนวโน้ม หรือซิงค์ข้อมูลกับเซิร์ฟเวอร์ภายนอก หากต้องการอ่านสัญญาณชีพ ให้ใช้ ReadRecordsRequest กับประเภทระเบียนที่เฉพาะเจาะจงและกรองตามช่วงเวลา

ตัวอย่างการอ่านข้อมูล BloodPressureRecord

suspend fun readBloodPressureRecords(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = BloodPressureRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (record in response.records) {
        // Process each blood pressure record
        val systolic = record.systolic
        val diastolic = record.diastolic
    }
}

หากต้องการซิงค์ข้อมูลสัญญาณชีพกับเซิร์ฟเวอร์แบ็กเอนด์ หรืออัปเดต Datastore ของแอปให้เป็นปัจจุบันอยู่เสมอด้วย Health Connect ให้ใช้ ChangeLogs ซึ่งช่วยให้คุณดึงข้อมูลรายการของระเบียนที่แทรก อัปเดต หรือลบตั้งแต่จุดเวลาที่เฉพาะเจาะจงได้ ซึ่งมีประสิทธิภาพมากกว่าการติดตามการเปลี่ยนแปลงด้วยตนเองหรือการอ่านข้อมูลทั้งหมดซ้ำๆ ดูข้อมูลเพิ่มเติมได้ที่หัวข้อซิงค์ข้อมูลกับ Health Connect

แนวทางปฏิบัติแนะนำ

โปรดทำตามหลักเกณฑ์ต่อไปนี้เพื่อปรับปรุงความน่าเชื่อถือของข้อมูลและประสบการณ์ของผู้ใช้

  • คำขอเขียนแบบกลุ่ม: หากต้องการลดค่าใช้จ่ายเพิ่มเติมสำหรับอินพุต/เอาต์พุตและยืดอายุการใช้งานแบตเตอรี่ ให้จัดกลุ่มจุดข้อมูลเป็นการเรียก insertRecords ครั้งเดียวโดยมีกลุ่มข้อมูลสูงสุด 1,000 รายการ แทนที่จะเขียนจุดข้อมูลแต่ละจุดแยกกัน
  • เขียนข้อมูลบ่อยๆ ระหว่างการติดตามแบบเรียลไทม์: สำหรับการอัปเดตบ่อยๆ จากเซ็นเซอร์ (เช่น เครื่องตรวจน้ำตาลแบบต่อเนื่องหรือเครื่องวัดอัตราการเต้นของหัวใจ) ให้เขียนข้อมูลเป็นกลุ่มๆ โดยเว้นระยะห่างสูงสุด 15 นาที เพื่อสร้างสมดุลระหว่างการอัปเดตแบบเรียลไทม์กับประสิทธิภาพของแบตเตอรี่
  • ใช้ WorkManager สำหรับการซิงค์ในเบื้องหลัง: ใช้ WorkManager สำหรับการเขียนที่เลื่อนออกไป เช่น การซิงค์ข้อมูลจากอุปกรณ์ที่ใช้ร่วมกันหรือบริการแบ็กเอนด์ ตั้งเป้าให้มีช่วงเวลา 15 นาทีสำหรับการเขียนแบบกลุ่ม
  • หลีกเลี่ยงการเขียนข้อมูลที่ซ้ำกัน: ใช้รหัสไคลเอ็นต์: เมื่อสร้างระเบียน ให้ตั้งค่า metadata.clientRecordId Health Connect จะใช้ข้อมูลนี้เพื่อระบุระเบียนที่ไม่ซ้ำกัน หากคุณพยายามเขียนบันทึกที่มี clientRecordId อยู่แล้ว Health Connect จะละเว้นรายการที่ซ้ำกันหรืออัปเดตบันทึกที่มีอยู่แทนการสร้างบันทึกใหม่ การตั้งค่า metadata.clientRecordId เป็นวิธีที่มีประสิทธิภาพที่สุดในการป้องกันการซ้ำกันระหว่างการลองซิงค์อีกครั้งหรือการติดตั้งแอปอีกครั้ง
    val record = StepsRecord(
        count = 100,
        startTime = startTime,
        endTime = endTime,
        startZoneOffset = ZoneOffset.UTC,
        endZoneOffset = ZoneOffset.UTC,
        metadata = Metadata(
            // Use a unique ID from your own database
            clientRecordId = "daily_steps_2023_10_27_user_123"
        )
    )
  • ตรวจสอบข้อมูลที่มีอยู่: ก่อนซิงค์ข้อมูล ให้ค้นหาระเบียนใน Health Connect ภายในช่วงเวลาที่ซิงค์เพื่อดูว่ามีข้อมูลจากแอปของคุณอยู่แล้วหรือไม่ เพื่อหลีกเลี่ยงข้อมูลที่ซ้ำกันหรือการเขียนทับข้อมูลที่ใหม่กว่า
  • ระบุเหตุผลที่ชัดเจนในการขอสิทธิ์: ใช้ขั้นตอน Permission.createIntent เพื่ออธิบายเหตุผลที่แอปต้องเข้าถึงข้อมูลสุขภาพ เช่น "เพื่อติดตามแนวโน้มความดันโลหิตและให้ข้อมูลเชิงลึก"
  • ปรับการประทับเวลาให้สอดคล้องกับการวัด: ตรวจสอบว่าการประทับเวลาของบันทึกแสดงเวลาที่ทำการวัดอย่างถูกต้อง สำหรับข้อมูลช่วงเวลา เช่น HeartRateRecord ให้ตรวจสอบว่า startTime และ endTime ถูกต้อง

การทดสอบ

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

เครื่องมือยืนยัน

  • Health Connect Toolbox: ใช้แอปที่ใช้ร่วมกันนี้เพื่อตรวจสอบระเบียนด้วยตนเอง ลบข้อมูลทดสอบ และจำลองการเปลี่ยนแปลงในฐานข้อมูล วิธีนี้เป็นวิธีที่ดีที่สุดในการยืนยันว่าระบบจัดเก็บระเบียนของคุณอย่างถูกต้อง
  • การทำ Unit Test ด้วย FakeHealthConnectClient: ใช้ไลบรารีการทดสอบเพื่อยืนยันวิธีที่แอปจัดการกับกรณีที่เกิดขึ้นไม่บ่อย เช่น การเพิกถอนสิทธิ์หรือข้อยกเว้น API โดยไม่ต้องใช้อุปกรณ์จริง

รายการตรวจสอบคุณภาพ

สถาปัตยกรรมทั่วไป

การติดตั้งใช้งาน Vitals มักประกอบด้วยสิ่งต่อไปนี้

ส่วนประกอบ จัดการ
ตัวควบคุมค่าสัญญาณชีพ การอ่านเซ็นเซอร์/อินพุต
ตรรกะการจัดกลุ่ม
เลเยอร์ที่เก็บ (รวมการดำเนินการของ Health Connect) แทรกบันทึกสัญญาณชีพ
อ่านบันทึกสัญญาณชีพ
ชั้น UI (จอแสดงผล): ค่าที่อ่านได้แบบเรียลไทม์
ข้อมูลย้อนหลัง
แผนภูมิและแนวโน้ม

การแก้ปัญหา

ลักษณะปัญหา สาเหตุที่เป็นไปได้ ความละเอียด
ไม่มีประเภทข้อมูล (เช่น ความดันโลหิต) ไม่มีสิทธิ์เขียนหรือตัวกรองเวลาไม่ถูกต้อง ตรวจสอบว่าคุณได้ขอและผู้ใช้ได้ให้สิทธิ์เข้าถึงประเภทข้อมูลที่เฉพาะเจาะจงแล้ว ตรวจสอบว่า ReadRecordsRequest ใช้ TimeRangeFilter ที่ครอบคลุมเวลาของการวัด ดูสิทธิ์
ระเบียนที่ซ้ำกันปรากฏขึ้น ไม่มี clientRecordId กำหนด clientRecordId ที่ไม่ซ้ำกันใน Metadata ของแต่ละระเบียน ซึ่งจะช่วยให้ Health Connect ทำการกรองข้อมูลที่ซ้ำกันออกได้หากมีการเขียนข้อมูลเดียวกัน 2 ครั้งระหว่างการลองซิงค์อีกครั้ง ดูแนวทางปฏิบัติแนะนำ
เขียนระเบียนไม่สำเร็จ หน่วยไม่ถูกต้องหรือค่าอยู่นอกช่วงที่ถูกต้อง Health Connect จะตรวจสอบค่าของบันทึก ตัวอย่างเช่น ค่าความดันโลหิตต้องอยู่ในช่วงที่สมเหตุสมผลทางสรีรวิทยา ดูเอกสารประกอบเกี่ยวกับประเภทข้อมูลเพื่อดูช่วงและหน่วยที่ถูกต้อง

ขั้นตอนการแก้ไขข้อบกพร่องที่พบบ่อย

ตรวจสอบสถานะสิทธิ์ เรียกใช้ getPermissionStatus() ทุกครั้งก่อนพยายามดำเนินการอ่านหรือเขียน ผู้ใช้สามารถเพิกถอนสิทธิ์ในการตั้งค่าระบบได้ทุกเมื่อ