Phát triển trải nghiệm về giấc ngủ 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 trải nghiệm theo dõi giấc ngủ trong ứng dụng, bạn có thể dùng Health Connect để làm những việc như:

  • Ghi dữ liệu về phiên ngủ
  • Ghi dữ liệu về các giai đoạn ngủ
  • Ghi dữ liệu giấc ngủ như tần số tim, độ bão hoà oxy và nhịp thở
  • Đọc dữ liệu giấc ngủ từ các ứng dụng khác

Hướng dẫn này mô tả cách xây dựng các tính năng liên quan đến giấc ngủ, bao gồm các loại dữ liệu, quá trình thực thi trong nền, quyền, quy trình làm việc được đề xuất và các phương pháp hay nhất.

Tổng quan: Xây dựng một ứng dụng theo dõi giấc ngủ toàn diện

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

  • Triển khai đúng các quyền dựa trên Quyền truy cập vào dữ liệu sức khoẻ.
  • Ghi lại phiên bằng SleepSessionRecord.
  • Ghi các loại dữ liệu như giai đoạn ngủ, nhịp tim và độ bão hoà oxy một cách nhất quán trong suốt phiên.
  • Quản lý việc thực thi trong nền đúng cách để xác minh việc thu thập dữ liệu liên tục qua đêm.
  • Đọc dữ liệu về phiên ngủ để tóm tắt và phân tích sau khi ngủ.

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 liên quan đến giấc ngủ:

Khái niệm chính

Health Connect biểu thị dữ liệu giấc ngủ bằng một vài thành phần cốt lõi. SleepSessionRecord đóng vai trò là bản ghi trung tâm về giấc ngủ, chứa các thông tin chi tiết như thời gian bắt đầu hoặc kết thúc và các giai đoạn ngủ. Trong một phiên, bạn có thể ghi lại nhiều loại dữ liệu như HeartRateRecord hoặc OxygenSaturationRecord.

Phiên giấc ngủ

Dữ liệu giấc ngủ được biểu thị bằng SleepSessionRecord. Mỗi bản ghi lưu trữ:

  • startTime
  • endTime
  • stages: Danh sách SleepSessionRecord.Stage bao gồm ngủ sâu, ngủ nông, ngủ REM và thức.
  • Siêu dữ liệu không bắt buộc của phiên (tiêu đề, ghi chú)

Ứng dụng có thể ghi nhiều loại dữ liệu liên quan đến một phiên.

Loại dữ liệu

Các loại dữ liệu phổ biến được ghi lại trong một phiên ngủ bao gồm:

Mỗi loại dữ liệu được lưu trữ dưới dạng một bản ghi riêng lẻ.

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

Ứng dụng theo dõi giấc ngủ thường cần chạy trong thời gian dài, thường là trong nền khi màn hình tắt. Khi xây dựng các tính năng liên quan đến giấc ngủ, bạn cần cân nhắc cách quản lý việc thực thi trong nền và yêu cầu các quyền cần thiết đối với dữ liệu giấc ngủ.

Thực thi trong nền

Ứng dụng theo dõi giấc ngủ thường chạy qua đêm khi màn hình tắt. Khi ở trạng thái này, bạn nên sử dụng:

  • Dịch vụ nền trước để thu thập dữ liệu
  • WorkManager để trì hoãn việc ghi hoặc đồng bộ hoá
  • Chiến lược phân lô để ghi dữ liệu chi tiết theo bản ghi thông thường, chẳng hạn như tần số tim

Duy trì tính liên tục bằng cách giữ cho mã phiên nhất quán trong tất cả các lần ghi.

Quyền

Ứng dụng của bạn phải yêu cầu các quyền liên quan của Health Connect trước khi đọc hoặc ghi dữ liệu giấc ngủ. Để 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. Các quyền phổ biến đối với dữ liệu giấc ngủ bao gồm phiên ngủ và các chỉ số như tần số tim hoặc độ bão hòa oxy.

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

  • android.permission.health.READ_SLEEP
  • android.permission.health.WRITE_SLEEP

Để thêm chức năng giấc ngủ 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 SleepSession.

Dưới đây là quyền bạn cần khai báo để có thể ghi dữ liệu giấc ngủ:

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

Để đọc dữ liệu về giấc ngủ, bạn cần yêu cầu các quyền sau:

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

Sau đây là ví dụ về cách yêu cầu quyền cho một phiên ngủ bao gồm dữ liệu về tần số tim, độ bão hòa oxy và nhịp thở:

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(SleepSessionRecord::class),
        HealthPermission.getWritePermission(SleepSessionRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(OxygenSaturationRecord::class),
        HealthPermission.getWritePermission(OxygenSaturationRecord::class),
        HealthPermission.getReadPermission(RespiratoryRateRecord::class),
        HealthPermission.getWritePermission(RespiratoryRateRecord::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.

Triển khai phiên ngủ

Phần này mô tả quy trình đề xuất để ghi lại dữ liệu giấc ngủ.

Để điều chỉnh các loại dữ liệu như HeartRateRecord hoặc OxygenSaturationRecord cho phù hợp với một phiên ngủ, hãy ghi lại các loại dữ liệu đó bằng dấu thời gian nằm trong khoảng từ startTime đến endTime của phiên ngủ. Health Connect không sử dụng giá trị nhận dạng phiên để liên kết phiên ngủ với dữ liệu chi tiết. Thay vào đó, mối liên kết được ngầm định thông qua các khoảng thời gian trùng lặp. Khi đọc dữ liệu giấc ngủ, bạn có thể sử dụng phạm vi thời gian của một phiên để truy vấn các kiểu dữ liệu liên quan, như trong phần Đọc dữ liệu giấc ngủ.

Ghi một phiên

Mặc dù dữ liệu thật chi tiết như tần số tim có thể được ghi lại trong suốt một phiên ngủ, nhưng SleepSessionRecord chỉ được ghi vào Health Connect sau khi phiên ngủ kết thúc, chẳng hạn như khi người dùng thức dậy. Bản ghi phải bao gồm startTime, endTime của phiên và danh sách các đối tượng SleepSessionRecord.Stage được ghi lại trong phiên, vì SleepSessionRecord yêu cầu endTime phải sau startTime.

Cách ghi dữ liệu về phiên ngủ:

  1. Tạo mã bản ghi ứng dụng khách riêng biệt.
  2. Khi người dùng thức dậy hoặc tính năng theo dõi giấc ngủ dừng lại, hãy thu thập tất cả các giai đoạn ngủ và tạo một SleepSessionRecord.
  3. Chèn bản ghi bằng insertRecords.

Ví dụ:

val clientRecordId = UUID.randomUUID().toString()
val sessionStartTime = LocalDateTime.of(2023, 10, 30, 22, 0).toInstant(ZoneOffset.UTC)
val sessionEndTime = LocalDateTime.of(2023, 10, 31, 7, 0).toInstant(ZoneOffset.UTC)

val stages = mutableListOf<SleepSessionRecord.Stage>()
// Add recorded stages, for example:
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(3600),
    endTime = sessionStartTime.plusSeconds(7200),
    stage = SleepSessionRecord.STAGE_TYPE_LIGHT)
)
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(7200),
    endTime = sessionStartTime.plusSeconds(10800),
    stage = SleepSessionRecord.STAGE_TYPE_DEEP)
)
// ... other stages

val session = SleepSessionRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    stages = stages,
    metadata = Metadata(clientRecordId = clientRecordId)
)

healthConnectClient.insertRecords(listOf(session))

Đọc dữ liệu giấc ngủ

Ứng dụng có thể đọc các phiên ngủ và dữ liệu liên quan để tóm tắt hoạt động, cung cấp thông tin chi tiết về sức khoẻ hoặc đồng bộ hoá dữ liệu với máy chủ bên ngoài. Ví dụ: bạn có thể đọc một SleepSessionRecord rồi truy vấn HeartRateRecord xảy ra trong cùng khoảng thời gian đó.

Đọc phiên có dữ liệu liên kết

Bạn có thể đọc phiên ngủ bằng cách sử dụng ReadRecordsRequest với SleepSessionRecord làm loại bản ghi, được lọc theo phạm vi thời gian. Để đọc dữ liệu liên quan cho một phiên nhất định, hãy tạo yêu cầu thứ hai cho loại dữ liệu đã chọn, chẳng hạn như HeartRateRecord – lọc theo startTime và endTime của phiên ngủ.

Ví dụ sau đây cho biết cách đọc các phiên ngủ có dữ liệu tần số tim liên quan trong một phạm vi thời gian nhất định:

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

    for (sleepRecord in response.records) {
        // Process each session
        val stages = sleepRecord.stages
        val notes = sleepRecord.notes

        // To read specific granular data (like heart rate) that occurred during
        // this session, use the session's startTime and endTime to filter
        // the request for that data type.
        val hrResponse = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    sleepRecord.startTime,
                    sleepRecord.endTime
                )
            )
        )
        for (heartRateRecord in hrResponse.records) {
            for (sample in heartRateRecord.samples) {
                val bpm = sample.beatsPerMinute
            }
        }
    }
}

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:

  • Ghi dữ liệu thường xuyên trong quá trình theo dõi hoạt động: Đối với hoạt động theo dõi, hãy ghi dữ liệu ngay khi có hoặc sau khoảng thời gian tối đa là 15 phút.
  • Sử dụng WorkManager để đồng bộ hoá trong nền: Sử dụng WorkManager cho các lượt ghi bị trì hoãn. Hãy đặt khoảng thời gian là 15 phút để cân bằng giữa dữ liệu theo thời gian thực và hiệu suất pin.
  • Yêu cầu ghi theo lô: Đừng ghi riêng lẻ từng sự kiện cảm biến. Chia nhỏ yêu cầu. Health Connect xử lý tối đa 1.000 bản ghi cho mỗi yêu cầu ghi.
  • Giữ cho mã phiên ổn định và duy nhất: Sử dụng giá trị nhận dạng nhất quán cho các phiên của bạn. Nếu một phiên được chỉnh sửa hoặc cập nhật, việc sử dụng cùng một mã nhận dạng sẽ giúp phiên đó không bị coi là một phiên mới, riêng biệt.
  • Sử dụng tính năng phân lô cho các loại dữ liệu: Để 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 của bạn vào một lệnh gọi insertRecords duy nhất thay vì ghi riêng từng điểm.
  • 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á, hãy truy vấn phạm vi thời gian để xem liệu bản ghi từ ứng dụng của bạn đã tồn tại hay chưa.
  • Đảm bảo dấu thời gian không trùng lặp: Xác minh rằng phiên mới không bắt đầu trước khi phiên trước đó kết thúc. Các phiên trùng lặp có thể gây ra xung đột trong trang tổng quan về hoạt động thể dục và các phép tính tóm tắt.
  • Đư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".
  • Kiểm thử các phiên chạy trong thời gian dài: Theo dõi mức tiêu thụ pin trong các phiên kéo dài vài giờ để xác minh rằng khoảng thời gian phân lô và mức sử dụng cảm biến không làm tiêu hao pin của thiết bị.
  • Căn chỉnh dấu thời gian với tốc độ cảm biến: Khớp dấu thời gian của bản ghi với tần suất thực tế của cảm biến để duy trì độ chân thực cao của dữ liệu.

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 tính năng theo dõi giấc ngủ thường bao gồm:

Thành phần Quản lý
Bộ điều khiển phiên Trạng thái phiên
Bộ hẹn giờ
Logic phân lô
Bộ điều khiển loại dữ liệu
Thu thập dữ liệu
Lớp kho lưu trữ (gói các thao tác của Health Connect:) Chèn phiên hoạt động
Chèn loại dữ liệu
Chèn giai đoạn ngủ
Đọc thông tin tóm tắt về phiên hoạt động
Lớp giao diện người dùng (Màn hình): Thời lượng
Các loại dữ liệu trực tiếp
Hình ảnh trực quan về các giai đoạn 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ụ: Tần số tim) 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 khớp với phiên. Xem phần Quyền.
Không ghi được phiên Dấu thời gian trùng lặp. Health Connect có thể từ chối các bản ghi trùng lặp với dữ liệu hiện có trong cùng một ứng dụng. Hãy xác thực rằng startTime của một phiên mới diễn ra sau endTime của phiên trước đó.
Không có dữ liệu cảm biến nào được ghi lại trong khi ngủ Dịch vụ nền trước đã bị tắt hoặc không hoạt động. Để thu thập dữ liệu cảm biến qua đêm khi màn hình tắt, bạn có thể sử dụng dịch vụ nền trước với foregroundServiceType="health".
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.

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.
Xác minh chế độ thực thi. Nếu ứng dụng của bạn không thu thập dữ liệu ở chế độ nền, hãy xác minh rằng bạn đã khai báo đúng quyền trong tệp AndroidManifest.xml và người dùng chưa đặt ứng dụng vào chế độ "Battery Restricted" (Hạn chế pin).