Phát triển trải nghiệm về các chỉ số sức khỏe bằng Health Connect

Hướng dẫn này tương thích với Health Connect phiên bản 1.1.0 trở lên.

Nếu muốn xây dựng một ứng dụng quản lý chỉ số sức khoẻ của người dùng, bạn có thể sử dụng Health Connect để làm những việc như:

  • Đọc dữ liệu về chỉ số sức khoẻ như huyết áp, tần số tim và thân nhiệt từ các ứng dụng khác
  • Ghi dữ liệu về chỉ số sức khỏe do ứng dụng hoặc thiết bị thông minh đã kết nối của bạn ghi lại
  • Theo dõi xu hướng và cung cấp thông tin chi tiết về sức khoẻ dựa trên dữ liệu về chỉ số quan trọng

Hướng dẫn này mô tả cách làm việc với các loại dữ liệu về dấu hiệu sinh tồn, bao gồm cả quyền, quy trình đọc và ghi cũng như các phương pháp hay nhất.

Tổng quan: Xây dựng một trình theo dõi chỉ số quan trọng toàn diện

Bạn có thể xây dựng trải nghiệm theo dõi toàn diện các chỉ số quan trọng bằng Health Connect bằng cách làm theo các bước chính sau:

  • Yêu cầu các quyền thích hợp cho các loại dữ liệu chỉ số quan trọng.
  • Ghi dữ liệu về dấu hiệu sinh tồn bằng các bản ghi như BloodPressureRecord, HeartRateRecord và các bản ghi khác về dấu hiệu sinh tồn.
  • Đọc dữ liệu về chỉ số sức khoẻ để hiển thị, phân tích hoặc đồng bộ hoá.
  • Sử dụng tính năng phân lô để ghi và đọc dữ liệu hiệu quả.

Quy trình này cho phép khả năng tương tác với các ứng dụng Health Connect khác và xác minh quyền truy cập dữ liệu do người dùng kiểm soát.

Trước khi bắt đầu

Trước khi triển khai các tính năng chỉ số quan trọng:

Khái niệm chính

Dữ liệu về dấu hiệu sinh tồn trong Health Connect được biểu thị bằng nhiều loại bản ghi, mỗi loại tương ứng với một phép đo sinh lý cụ thể. Không giống như các buổi tập thể dục, chỉ số quan trọng thường được ghi lại dưới dạng dữ liệu theo thời điểm hoặc theo khoảng thời gian.

Loại dữ liệu về chỉ số quan trọng

Dữ liệu về chỉ số quan trọng được biểu thị bằng từng loại bản ghi. Sau đây là các loại phổ biến:

  • BloodPressureRecord: Biểu thị một chỉ số huyết áp, bao gồm huyết áp tâm thu và huyết áp tâm trương, cũng như tư thế cơ thể.
  • HeartRateRecord: Biểu thị một loạt các phép đo tần số tim.
  • RestingHeartRateRecord: Biểu thị một phép đo tần số tim lúc nghỉ ngơi.
  • BodyTemperatureRecord: Biểu thị một chỉ số nhiệt độ cơ thể, bao gồm cả vị trí đo.
  • BloodGlucoseRecord: Biểu thị một chỉ số đường huyết, bao gồm cả mối liên hệ với bữa ăn và nguồn mẫu xét nghiệm.
  • OxygenSaturationRecord: Biểu thị một chỉ số đo lường độ bão hoà oxy trong máu.
  • RespiratoryRateRecord: Biểu thị một lần đo nhịp thở.

Để xem danh sách đầy đủ các loại dữ liệu, hãy xem phần Các loại dữ liệu của Health Connect.

Điều cần cân nhắc khi phát triển ứng dụng

Dữ liệu về chỉ số quan trọng có thể nhạy cảm và các ứng dụng có thể cần ghi dữ liệu để phản hồi các phép đo từ cảm biến hoặc hoạt động đầu vào của người dùng, hoặc đồng bộ hoá dữ liệu từ phần phụ trợ. Quyền là yếu tố quan trọng để xử lý dữ liệu về dấu hiệu sinh tồn.

Quyền

Ứng dụng của bạn phải yêu cầu các quyền liên quan trong Health Connect trước khi đọc hoặc ghi dữ liệu về chỉ số quan trọng. Các quyền phổ biến đối với chỉ số sức khoẻ bao gồm huyết áp, tần số tim, thân nhiệt, đường huyết, độ bão hòa oxy và nhịp thở. Điều này bao gồm:

Sau đây là ví dụ về cách yêu cầu quyền truy cập vào dữ liệu huyết áp, tần số tim và thân nhiệt:

Sau khi tạo một phiên bản ứng dụng, ứng dụng của bạn cần yêu cầu người dùng cấp quyền. Người dùng phải được phép cấp hoặc từ chối cấp quyền bất cứ lúc nào. Để thực hiện việc này, hãy tạo một tập hợp quyền cho các kiểu dữ liệu bắt buộc. Trước tiên, bạn cần khai báo các quyền trong tập hợp này ở tệp kê khai 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)
    )
Hãy sử dụng getGrantedPermissions để xem ứng dụng của bạn đã được cấp các quyền cần thiết chưa. Nếu chưa, hãy sử dụng createRequestPermissionResultContract để yêu cầu các quyền đó. Thao tác này sẽ hiện màn hình các quyền của 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.") }
    }
}
Vì người dùng có thể cấp hoặc thu hồi quyền bất cứ lúc nào, nên ứng dụng của bạn cần kiểm tra quyền mỗi lần trước khi sử dụng và xử lý các trường hợp mất quyền.

Để yêu cầu quyền, hãy gọi hàm 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

Nếu bạn chỉ cần yêu cầu quyền cho một loại dữ liệu, chẳng hạn như huyết áp, thì chỉ cần thêm loại dữ liệu đó vào bộ quyền:

Quyền truy cập vào dữ liệu huyết áp được bảo vệ bằng các quyền sau:

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

Để thêm chức năng huyết áp vào ứng dụng, hãy bắt đầu bằng cách yêu cầu quyền cho kiểu dữ liệu BloodPressureRecord.

Dưới đây là quyền bạn cần khai báo để có thể ghi dữ liệu huyết áp:

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

Để đọc dữ liệu huyết áp, bạn cần yêu cầu các quyền sau:

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

Ghi dữ liệu về chỉ số sức khoẻ

Phần này mô tả cách ghi dữ liệu về dấu hiệu sinh tồn vào Health Connect. Dữ liệu về dấu hiệu sinh tồn thường được ghi dưới dạng các bản ghi riêng lẻ. Nếu bạn đang ghi nhiều bản ghi cùng một lúc, chẳng hạn như đồng bộ hoá từ cảm biến hoặc phần phụ trợ, hãy sử dụng tính năng phân lô.

Ví dụ về cách viết 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))
}

Viết hàng loạt

Nếu ứng dụng của bạn cần ghi nhiều điểm dữ liệu, chẳng hạn như đồng bộ hoá dữ liệu từ một thiết bị thông minh hoặc dịch vụ phụ trợ, thì bạn nên ghi theo lô để cải thiện hiệu suất và giảm mức tiêu thụ pin. Health Connect có thể xử lý tối đa 1.000 bản ghi trong một yêu cầu ghi.

Đoạn mã sau đây cho biết cách ghi nhiều bản ghi cùng một lúc:

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

Đọc dữ liệu về chỉ số quan trọng

Ứng dụng có thể đọc dữ liệu sức khoẻ để hiển thị kết quả đo lường, phân tích xu hướng hoặc đồng bộ hoá dữ liệu với máy chủ bên ngoài. Để đọc chỉ số quan trọng, hãy sử dụng ReadRecordsRequest với loại bản ghi cụ thể và lọc theo phạm vi thời gian.

Ví dụ về cách đọc dữ liệu 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
    }
}

Nếu bạn cần đồng bộ hoá dữ liệu về chỉ số quan trọng với máy chủ phụ trợ hoặc cập nhật kho dữ liệu của ứng dụng bằng Health Connect, hãy sử dụng ChangeLogs. Nhờ đó, bạn có thể truy xuất danh sách các bản ghi đã chèn, cập nhật hoặc xoá kể từ một thời điểm cụ thể. Cách này hiệu quả hơn so với việc theo dõi các thay đổi theo cách thủ công hoặc đọc lặp lại tất cả dữ liệu. Để biết thêm thông tin, hãy xem bài viết Đồng bộ hoá dữ liệu với Health Connect.

Các phương pháp hay nhất

Hãy làm theo các nguyên tắc sau để cải thiện độ tin cậy của dữ liệu và trải nghiệm người dùng:

  • Yêu cầu ghi theo lô: Để giảm mức hao tổn Đầu vào/Đầu ra và duy trì thời lượng pin, hãy nhóm các điểm dữ liệu thành một lệnh gọi insertRecords duy nhất với các lô có tối đa 1.000 bản ghi, thay vì ghi riêng lẻ từng điểm.
  • Ghi dữ liệu thường xuyên trong quá trình theo dõi trực tiếp: Đối với các bản cập nhật thường xuyên từ cảm biến (như máy theo dõi đường huyết liên tục hoặc máy theo dõi tần số tim), hãy ghi dữ liệu theo lô trong khoảng thời gian tối đa 15 phút để cân bằng giữa việc cập nhật theo thời gian thực và hiệu suất pin.
  • Sử dụng WorkManager để đồng bộ hoá trong nền: Sử dụng WorkManager cho các hoạt động ghi bị trì hoãn, chẳng hạn như đồng bộ hoá dữ liệu từ thiết bị đồng hành hoặc dịch vụ phụ trợ. Cố gắng đặt khoảng thời gian 15 phút cho các lượt ghi theo lô.
  • Tránh ghi dữ liệu trùng lặp: Sử dụng mã ứng dụng khách: Khi tạo bản ghi, hãy đặt metadata.clientRecordId. Health Connect sử dụng giá trị này để xác định các bản ghi riêng biệt. Nếu bạn cố gắng ghi một bản ghi có clientRecordId đã tồn tại, Health Connect sẽ bỏ qua bản ghi trùng lặp hoặc cập nhật bản ghi hiện có thay vì tạo bản ghi mới. Việc đặt metadata.clientRecordId là cách hiệu quả nhất để ngăn chặn các bản sao trong quá trình thử lại đồng bộ hoá hoặc cài đặt lại ứng dụng.
    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"
        )
    )
  • Kiểm tra dữ liệu hiện có: Trước khi đồng bộ hoá dữ liệu, hãy truy vấn Health Connect để tìm các bản ghi trong phạm vi thời gian đồng bộ hoá nhằm xem dữ liệu từ ứng dụng của bạn đã tồn tại hay chưa, tránh trùng lặp hoặc ghi đè dữ liệu mới hơn.
  • Đưa ra lý do rõ ràng cho việc yêu cầu cấp quyền: Sử dụng quy trình Permission.createIntent để giải thích lý do ứng dụng của bạn cần quyền truy cập vào dữ liệu sức khoẻ, ví dụ: "Để theo dõi xu hướng huyết áp và cung cấp thông tin chi tiết".
  • Căn chỉnh dấu thời gian với số liệu đo lường: Xác minh rằng dấu thời gian của bản ghi phản ánh chính xác thời điểm thực hiện số liệu đo lường. Đối với dữ liệu khoảng thời gian như HeartRateRecord, hãy xác minh rằng startTime và endTime là chính xác.

Thử nghiệm

Để xác minh tính chính xác của dữ liệu và trải nghiệm người dùng chất lượng cao, hãy làm theo các chiến lược kiểm thử này và tham khảo tài liệu chính thức về Kiểm thử các trường hợp sử dụng hàng đầu.

Công cụ xác minh

  • Hộp công cụ Health Connect: Sử dụng ứng dụng đồng hành này để kiểm tra bản ghi theo cách thủ công, xoá dữ liệu kiểm thử và mô phỏng các thay đổi đối với cơ sở dữ liệu. Đây là cách tốt nhất để xác minh rằng hồ sơ của bạn đang được lưu trữ chính xác.
  • Kiểm thử đơn vị bằng FakeHealthConnectClient: Sử dụng thư viện kiểm thử để xác minh cách ứng dụng xử lý các trường hợp hiếm gặp, chẳng hạn như thu hồi quyền hoặc ngoại lệ API mà không cần thiết bị thực.

Danh sách kiểm tra chất lượng

Kiến trúc điển hình

Quá trình triển khai chỉ số quan trọng thường bao gồm:

Thành phần Quản lý
Bộ điều khiển chỉ số quan trọng Đọc cảm biến/đầu vào
Logic phân lô
Lớp kho lưu trữ (gói các thao tác của Health Connect:) Chèn bản ghi chỉ số quan trọng
Đọc bản ghi chỉ số quan trọng
Lớp giao diện người dùng (Màn hình): Chỉ số theo thời gian thực
Dữ liệu trong quá khứ
Biểu đồ và xu hướng

Khắc phục sự cố

Dấu hiệu Nguyên nhân có thể gây ra lỗi Độ phân giải
Thiếu loại dữ liệu (Ví dụ: Huyết áp) Thiếu quyền ghi hoặc bộ lọc thời gian không chính xác. Kiểm tra để đảm bảo bạn đã yêu cầu và người dùng đã cấp quyền truy cập vào loại dữ liệu cụ thể. Xác minh rằng ReadRecordsRequest của bạn sử dụng TimeRangeFilter bao gồm thời gian đo lường. Xem phần Quyền.
Bản ghi trùng lặp xuất hiện Thiếu clientRecordId. Chỉ định một clientRecordId duy nhất trong Metadata của mỗi bản ghi. Điều này cho phép Health Connect thực hiện việc loại bỏ trùng lặp nếu cùng một dữ liệu được ghi hai lần trong quá trình thử đồng bộ hoá lại. Xem Các phương pháp hay nhất.
Không ghi được bản ghi Đơn vị không chính xác hoặc giá trị nằm ngoài phạm vi hợp lệ. Health Connect xác thực các giá trị bản ghi. Ví dụ: giá trị huyết áp phải nằm trong phạm vi hợp lý về mặt sinh lý. Hãy xem tài liệu về loại dữ liệu để biết phạm vi và đơn vị hợp lệ.

Các bước gỡ lỗi phổ biến

Kiểm tra trạng thái quyền. Luôn gọi getPermissionStatus() trước khi thực hiện thao tác đọc hoặc ghi. Người dùng có thể thu hồi quyền trong phần cài đặt hệ thống bất cứ lúc nào.