Phát triển trải nghiệm tập luyện bằng Health Connect

Nếu muốn tạo trải nghiệm tập luyện trong ứng dụng, bạn có thể dùng Health Connect để làm những việc như:

• Ghi phiên hoạt động tập thể dục
• Ghi dữ liệu về tuyến đường tập luyện
• Ghi các chỉ số về bài tập như tần số tim, tốc độ và quãng đường
• Đọc dữ liệu về hoạt động tập luyện từ các ứng dụng khác

Hướng dẫn này mô tả cách tạo các tính năng tập luyện này, bao gồm các loại dữ liệu, quá trình thực thi ở chế độ nền, quyền, quy trình công việc được đề xuất và các phương pháp hay nhất.

Tổng quan: Xây dựng một trình theo dõi bài tập toàn diện

Bạn có thể tạo một trải nghiệm theo dõi hoạt động tập luyện 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 chính xác các quyền dựa trên Quyền truy cập vào dữ liệu sức khoẻ.
• Ghi lại các phiên bằng ExerciseSessionRecord.
• Ghi dữ liệu tập luyện một cách nhất quán trong phiên.
• Quản lý việc thực thi trong nền một cách thích hợp để xác minh việc liên tục thu thập dữ liệu.
• Đọc dữ liệu phiên để xem bản tóm tắt và phân tích sau buổi tập.

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 tập luyện:

• Tích hợp Health Connect bằng cách sử dụng phần phụ thuộc phù hợp.
• Tạo một thực thể HealthConnectClient.
• Xác minh rằng ứng dụng của bạn triển khai quy trình cấp quyền khi bắt đầu chạy dựa trên Quyền truy cập vào dữ liệu sức khoẻ.
• Nếu quy trình làm việc của bạn sử dụng GPS, hãy thiết lập quyền truy cập thông tin vị trí và dịch vụ trên nền trước.

Khái niệm chính

Health Connect biểu thị dữ liệu về hoạt động tập luyện bằng một số thành phần cốt lõi. ExerciseSessionRecord đóng vai trò là bản ghi trung tâm cho một bài tập, chứa các thông tin chi tiết như thời gian bắt đầu hoặc thời gian kết thúc và loại bài tập. Trong một phiên, nhiều loại dữ liệu như HeartRateRecord hoặc SpeedRecord có thể được ghi lại. Đối với các hoạt động ngoài trời, ExerciseRoute lưu trữ dữ liệu GPS được liên kết với phiên tương ứng.

Phiên hoạt động tập thể dục

ExerciseSessionRecord là bản ghi trung tâm cho dữ liệu tập luyện, đại diện cho một phiên tập luyện duy nhất. Mỗi bản ghi lưu trữ:

• startTime
• endTime
• exerciseType
• Siêu dữ liệu không bắt buộc của phiên (tiêu đề, ghi chú)

ExerciseSessionRecord cũng có thể chứa các tuyến đường tập thể dục, vòng chạy và đoạn đường trong dữ liệu của mình. Ngoài ra, các kiểu dữ liệu khác như HeartRateRecord hoặc SpeedRecord có thể được ghi lại trong một phiên và được liên kết với phiên đó.

Các loại dữ liệu được liên kết

Dữ liệu liên kết với các phiên tập luyện được biểu thị bằng các loại bản ghi riêng lẻ. Sau đây là các loại phổ biến:

• HeartRateRecord: Đại diện cho một loạt các phép đo tần số tim.
• SpeedRecord: Biểu thị một loạt các phép đo tốc độ.
• DistanceRecord: Biểu thị khoảng cách đã đi được giữa các lần đọc.
• TotalCaloriesBurnedRecord: Biểu thị tổng lượng calo đã đốt cháy giữa các lần đọc.
• ElevationGainedRecord: Biểu thị độ cao đạt được giữa các lần đọc.
• StepsCadenceRecord: Biểu thị nhịp độ bước chân giữa các lần đọc.
• PowerRecord: Biểu thị công suất đầu ra giữa các lần đọc, thường thấy trong các hoạt động như đạp xe.

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

Tuyến đường tập thể dục

Bạn có thể liên kết một tuyến đường với các bài tập ngoài trời bằng cách sử dụng ExerciseRoute. Các tuyến đường bao gồm các đối tượng ExerciseRoute.Location tuần tự, mỗi đối tượng chứa:

• Vĩ độ và kinh độ
• Độ cao không bắt buộc
• Phương hướng không bắt buộc
• Thông tin về độ chính xác
• Dấu thời gian

Liên kết các tuyến đường của phiên

ExerciseRoute chứa dữ liệu vị trí tuần tự cho một phiên tập thể dục. Dữ liệu này không được coi là một bản ghi độc lập trong Health Connect. Thay vào đó, bạn cung cấp dữ liệu ExerciseRoute khi chèn hoặc cập nhật một ExerciseSessionRecord.

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

Các ứng dụng theo dõi hoạt động tập luyện thường cần chạy trong thời gian dài, thường xuyên ở chế độ nền khi màn hình tắt. Khi xây dựng các tính năng tập luyện, bạn cần cân nhắc cách quản lý việc thực thi ở chế độ nền và yêu cầu các quyền cần thiết đối với dữ liệu tập luyện.

Chạy ở chế độ nền

Các ứng dụng tập luyện thường chạy khi màn hình tắt. Khi ở trạng thái này, bạn nên sử dụng:

• Dịch vụ trên nền trước để lấy mẫu vị trí và cảm biến
• WorkManager để ghi hoặc đồng bộ hoá bị hoãn lại
• Chiến lược tạo lô để ghi bản ghi thông thường

Duy trì tính liên tục bằng cách giữ mã phiên nhất quán trên tất cả các lượt 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 tập luyện. Các quyền thường gặp đối với bài tập thể dục bao gồm các phiên tập thể dục, tuyến đường tập thể dục và các chỉ số như tần số tim hoặc tốc độ. Trong đó có:

• Phiên tập thể dục: Quyền đọc và ghi cho ExerciseSessionRecord.
• Tuyến đường tập thể dục: Quyền đọc và ghi cho ExerciseRoute.
• Tần số tim: Quyền đọc và ghi đối với HeartRateRecord.
• Tốc độ: Quyền đọc và ghi cho SpeedRecord.
• Khoảng cách: Quyền đọc và ghi đối với DistanceRecord.
• Lượng calo: Quyền đọc và ghi cho TotalCaloriesBurnedRecord.
• Mức tăng độ cao: Quyền đọc và ghi đối với ElevationGainedRecord.
• Nhịp độ bước chân: Quyền đọc và ghi cho StepsCadenceRecord.
• Nguồn: Quyền đọc và ghi đối với PowerRecord.
• Các bước: Quyền đọc và ghi cho StepsRecord.

Sau đây là ví dụ về cách yêu cầu nhiều quyền cho một phiên tập luyện có dữ liệu về tuyến đường, tần số tim, khoảng cách, lượng calo, tốc độ và số bước:

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.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(ExerciseSessionRecord::class),
  HealthPermission.getWritePermission(ExerciseSessionRecord::class),
  HealthPermission.getReadPermission(ExerciseRoute::class),
  HealthPermission.getWritePermission(ExerciseRoute::class),
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(SpeedRecord::class),
  HealthPermission.getWritePermission(SpeedRecord::class),
  HealthPermission.getReadPermission(DistanceRecord::class),
  HealthPermission.getWritePermission(DistanceRecord::class),
  HealthPermission.getReadPermission(TotalCaloriesBurnedRecord::class),
  HealthPermission.getWritePermission(TotalCaloriesBurnedRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::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.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

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 khi sử dụng và xử lý các trường hợp mất quyền.

Để yêu cầu cấp quyền, hãy gọi hàm checkPermissionsAndRun:

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

Nếu chỉ cần yêu cầu quyền truy cập đối với một loại dữ liệu duy nhất, chẳng hạn như nhịp tim, hãy chỉ thêm loại dữ liệu đó vào nhóm quyền:

Quyền truy cập vào tần số tim được bảo vệ bằng các quyền sau:

• android.permission.health.READ_HEART_RATE
• android.permission.health.WRITE_HEART_RATE

Để thêm chức năng tần số tim 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 HeartRateRecord.

Dưới đây là quyền bạn cần khai báo để có thể ghi tần số tim:

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

Để đọc tần số tim, bạn cần yêu cầu các quyền sau:

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

Triển khai một phiên tập luyện

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

Bắt đầu phiên

Cách tạo một bài tập mới:

1. Tạo mã nhận dạng phiên duy nhất: Xác minh mã nhận dạng này có ổn định hay không. Nếu quy trình ứng dụng của bạn bị huỷ và khởi động lại, bạn phải có thể tiếp tục sử dụng cùng một mã nhận dạng để ngăn các phiên bị phân mảnh.
2. Đặt metadata.clientRecordId để ngăn trùng lặp trong quá trình đồng bộ hoá lại.
3. Viết ExerciseSessionRecord: Thêm thời gian bắt đầu.
4. Bắt đầu thu thập Loại dữ liệu và dữ liệu GPS: Chỉ bắt đầu thu thập những dữ liệu này sau khi bản ghi phiên được khởi tạo thành công.

Ví dụ:

val sessionId = UUID.randomUUID().toString()
val sessionClientId = UUID.randomUUID().toString()

val session = ExerciseSessionRecord(
    id = sessionId,
    exerciseType = ExerciseType.EXERCISE_TYPE_RUNNING,
    startTime = Instant.now(),
    endTime = null,
    metadata = Metadata(clientRecordId = sessionClientId),
)

healthConnectClient.insertRecords(listOf(session))

Ghi lại tuyến đường tập thể dục

Để tìm hiểu thêm về hướng dẫn đọc, hãy xem phần Đọc dữ liệu thô.

Khi ghi lại tuyến đường tập thể dục, bạn nên xử lý dữ liệu theo lô. Điều này có nghĩa là thay vì lưu từng điểm GPS riêng lẻ khi điểm đó xuất hiện, bạn sẽ thu thập một nhóm điểm và lưu tất cả các điểm đó cùng một lúc trong một lệnh gọi duy nhất.

Điều này rất quan trọng vì mỗi khi ứng dụng của bạn đọc hoặc ghi vào Health Connect, ứng dụng sẽ tiêu tốn một chút pin và sức mạnh xử lý.

Đoạn mã sau đây cho biết cách ghi theo lô:

// 1. Create a list to hold your route locations
val routeLocations = mutableListOf<ExerciseRoute.Location>()

// 2. Add points to your list as the exercise happens
routeLocations.add(
    ExerciseRoute.Location(
        time = Instant.now(),
        latitude = 37.7749,
        longitude = -122.4194
    )
)

// ... keep adding points over a period of time ...

// 3. Save the whole list at once (Batching)
val session = ExerciseSessionRecord(
    startTime = startTime,
    endTime = endTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    // We pass the whole list here
    exerciseRoute = ExerciseRoute(routeLocations)
)

healthConnectClient.insertRecords(listOf(session))

Kết thúc phiên

Sau khi bạn dừng thu thập dữ liệu:

• Cập nhật bản ghi: Ứng dụng của bạn cập nhật ExerciseSessionRecord bằng một endTime.
• Hoàn tất dữ liệu: Bạn có thể tính toán các giá trị tóm tắt (chẳng hạn như tổng quãng đường hoặc tốc độ trung bình) và ghi các giá trị đó dưới dạng các bản ghi bổ sung.

val finishedSession = session.copy(endTime = Instant.now())
healthConnectClient.updateRecords(listOf(finishedSession))

Đọc dữ liệu tập luyện

Các ứng dụng có thể đọc các phiên tập thể dục 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ột máy chủ bên ngoài. Ví dụ: bạn có thể đọc một ExerciseSessionRecord rồi truy vấn HeartRateRecord hoặc DistanceRecord đã xảy ra trong cùng khoảng thời gian đó.

Nếu cần đồng bộ hoá dữ liệu tập luyện với một 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. Điều này cho phép bạn truy xuất danh sách các bản ghi đã được chèn, cập nhật hoặc xoá kể từ một thời điểm cụ thể, 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 tất cả dữ liệu nhiều lần. Để 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ác phiên

Để đọc các phiên tập thể dục, hãy dùng ReadRecordsRequest với ExerciseSessionRecord làm loại. Bạn thường lọc dữ liệu này theo một phạm vi thời gian cụ thể.

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

    for (exerciseRecord in response.records) {
        // Process each session
        val exerciseType = exerciseRecord.exerciseType
        val notes = exerciseRecord.notes
    }
}

Đọc dữ liệu về tuyến đường

Mặc dù dữ liệu ExerciseRoute được ghi trong một phiên tập thể dục, nhưng bạn phải đọc dữ liệu này riêng. Sử dụng phương thức getExerciseRoute() với mã nhận dạng của phiên để đọc dữ liệu tuyến đường của phiên:

suspend fun readExerciseRoute(
    healthConnectClient: HealthConnectClient,
    exerciseSessionRecord: ExerciseSessionRecord
) {
    // Check if the session has a route
    val route = healthConnectClient.getExerciseRoute(
        exerciseSessionRecordId = exerciseSessionRecord.metadata.id
    )

    when (route) {
        is ExerciseRouteResponse.Success -> {
            val locations = route.exerciseRoute.locations
            for (location in locations) {
                // Use latitude, longitude, and altitude
            }
        }
        is ExerciseRouteResponse.NoData -> {
            // Handle case where no route exists
        }
        is ExerciseRouteResponse.ConsentRequired -> {
            // Handle case where permissions are missing
        }
    }
}

Đọc các loại dữ liệu

Để đọc dữ liệu chi tiết cụ thể (chẳng hạn như tần số tim) xảy ra trong một phiên, hãy sử dụng startTime và endTime của phiên để lọc yêu cầu cho loại dữ liệu đó.

suspend fun readHeartRateData(
    healthConnectClient: HealthConnectClient,
    exerciseSession: ExerciseSessionRecord
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(
                exerciseSession.startTime,
                exerciseSession.endTime
            )
        )
    )

    for (heartRateRecord in response.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 này để cải thiện độ tin cậy của dữ liệu và trải nghiệm người dùng:

• Tần suất ghi
  • Theo dõi đang hoạt động(Nền trước): Đối với các bài tập đang hoạt động, hãy ghi dữ liệu khi dữ liệu có sẵn hoặc trong khoảng thời gian tối đa là 15 phút.
  • Đồng bộ hoá ở chế độ nền: Sử dụng WorkManager để ghi hoãn. Đặ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.
  • Xử lý hàng loạt: Không ghi từng sự kiện cảm biến riêng lẻ. Phân đoạn các yêu cầu của bạn. Health Connect xử lý tối đa 1.000 bản ghi cho mỗi yêu cầu ghi.
• Giữ mã nhận dạng phiên ổn định và duy nhất: Sử dụng các 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 tập luyệ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ẽ ngăn phiên đó bị coi là một phiên tập luyện mới, riêng biệt.
• Sử dụng tính năng xử lý hàng loạt cho cả loại dữ liệu và điểm trên tuyến đường: Để giảm chi phí đầu vào/đầu ra và tiết kiệm pin, hãy nhóm các điểm dữ liệu thành một lệnh gọi insertRecords duy nhất thay vì ghi từng điểm riêng lẻ.

• Tránh ghi dữ liệu trùng lặp: Sử dụng mã ứng dụng Khi tạo bản ghi, hãy đặt một metadata.clientRecordId. Health Connect sử dụng thông tin 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. Đặt metadata.clientRecordId là cách hiệu quả nhất để ngăn chặn các bản sao trong quá trình đồng bộ hoá lại 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 có bản ghi nào từ ứng dụng của bạn đã tồn tại hay chưa.

• Xác thực độ chính xác của GPS: Lọc các mẫu GPS có độ chính xác thấp (Ví dụ: các điểm có bán kính độ chính xác theo phương ngang cao) trước khi ghi vào ExerciseRoute để xác minh rằng bản đồ trông gọn gàng và chuyên nghiệp.

• Đảm bảo dấu thời gian không trùng lặp: Xác minh rằng một phiên mới không bắt đầu trước khi phiên trước kết thúc. Các phiên tập luyện chồng chéo có thể gây ra xung đột trong bảng điều khiển và các phép tính tóm tắt về hoạt động thể dục.

• Đưa ra lý do rõ ràng cho 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ẻ, chẳng hạn như "Để lập bản đồ các lần chạy và tính toán lượng calo đốt cháy".

• Hỗ trợ tạm dừng và tiếp tục: Xác minh rằng ứng dụng của bạn xử lý các thao tác tạm dừng một cách chính xác. Khi người dùng tạm dừng, hãy ngừng thu thập các điểm trên tuyến đường và loại dữ liệu để tốc độ và thời lượng trung bình vẫn chính xác.

• Kiểm thử các phiên hoạt động kéo dài: Theo dõi mức tiêu thụ pin trong các phiên hoạt động kéo dài vài giờ để xác minh rằng khoảng thời gian theo lô và mức sử dụng cảm biến không làm hao pin thiết bị.

• Căn chỉnh dấu thời gian với tốc độ cảm biến: Điều chỉnh dấu thời gian của bản ghi cho phù hợp với tần suất thực tế của cảm biến (ví dụ: 1 Hz đối với GPS) để duy trì độ trung 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 bổ trợ này để kiểm tra các 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 các bản ghi của bạn đang được lưu trữ đúng cách.
• 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 của bạn xử lý các trường hợp đặc biệt, 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

Một quy trình triển khai bài tập thường bao gồm:

Khắc phục sự cố

Các bước gỡ lỗi thường gặp

• Kiểm tra trạng thái Quyền: Luôn gọi getPermissionStatus() trước khi thử 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 các quyền chính xác trong AndroidManifest.xml và người dùng chưa đặt ứng dụng ở chế độ "Hạn chế sử dụng pin".