Theo dõi số bước

Health Connect cung cấp loại dữ liệu số bước để ghi lại số bước bằng StepsRecord. Số bước là một chỉ số đo lường cơ bản trong tính năng theo dõi sức khoẻ và hoạt động thể chất.

Đọc dữ liệu về số bước trên thiết bị di động

Với Android 14 (API cấp 34) và Tiện ích SDK phiên bản 20 trở lên, Health Connect cung cấp tính năng đếm bước trên thiết bị. Nếu bạn đã cấp quyền READ_STEPS cho bất kỳ ứng dụng nào, Health Connect sẽ bắt đầu ghi lại số bước đi từ thiết bị chạy Android và người dùng sẽ thấy dữ liệu về số bước đi được tự động thêm vào các mục Số bước đi của Health Connect.

Để kiểm tra xem tính năng đếm bước trên thiết bị có hoạt động hay không, bạn cần xác minh rằng thiết bị đang chạy Android 14 (API cấp 34) và có ít nhất SDK phiên bản tiện ích 20. Bạn có thể sử dụng mã sau:

val isStepTrackingAvailable =
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
        SdkExtensions.getExtensionVersion(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) >= 20

Số bước di chuyển trên thiết bị di động do Health Connect ghi lại có DataOrigin được đặt thành tên gói android. Nếu ứng dụng của bạn chỉ đọc số bước tổng hợp bằng cách sử dụng aggregate và không lọc theo DataOrigin, thì số bước trên thiết bị sẽ tự động được đưa vào tổng số.

Nếu ứng dụng của bạn cần đọc số bước trên thiết bị hoặc nếu ứng dụng hiển thị dữ liệu về số bước được phân tích theo ứng dụng hoặc thiết bị nguồn, bạn có thể truy vấn các bản ghi có DataOrigin là android. Nếu ứng dụng của bạn cho thấy thông tin phân bổ cho dữ liệu bước, bạn nên phân bổ dữ liệu từ gói Android cho thiết bị hiện tại. Bạn có thể thực hiện việc này bằng cách sử dụng một nhãn như "Điện thoại của bạn", truy xuất tên thiết bị bằng Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) hoặc kiểm tra trường Device trong siêu dữ liệu của bản ghi.

Ví dụ sau đây cho thấy cách đọc dữ liệu tổng hợp về số bước đi trên thiết bị di động bằng cách lọc theo nguồn dữ liệu android:

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = setOf(DataOrigin("android"))
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Đếm bước trên thiết bị

Tìm hiểu kỹ hơn về tính năng đếm bước trên thiết bị:

  • Sử dụng cảm biến: Health Connect sử dụng cảm biến TYPE_STEP_COUNTER từ SensorManager. Cảm biến này được tối ưu hoá để tiêu thụ ít điện năng, nên rất phù hợp để theo dõi số bước liên tục ở chế độ nền.
  • Độ chi tiết của dữ liệu: Để tiết kiệm pin, dữ liệu về bước đi thường được xử lý theo lô và ghi vào cơ sở dữ liệu của Health Connect không thường xuyên hơn 1 lần/phút.
  • Phân bổ: Như đã đề cập trước đó, tất cả các bước do tính năng trên thiết bị này ghi lại đều được phân bổ cho tên gói android trong DataOrigin.
  • Kích hoạt: Cơ chế đếm bước trên thiết bị chỉ hoạt động khi có ít nhất một ứng dụng trên thiết bị được cấp quyền READ_STEPS trong Health Connect.

Kiểm tra phạm vi sử dụng Health Connect

Trước khi cố gắng sử dụng Health Connect, ứng dụng của bạn phải xác minh rằng Health Connect có trên thiết bị của người dùng. Health Connect có thể không được cài đặt sẵn trên một số thiết bị hoặc có thể bị tắt. Bạn có thể kiểm tra phạm vi cung cấp bằng phương thức HealthConnectClient.getSdkStatus().

Cách kiểm tra phạm vi sử dụng Health Connect

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // Optionally redirect to package installer to find a provider, for example:
      val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
      context.startActivity(
        Intent(Intent.ACTION_VIEW).apply {
          setPackage("com.android.vending")
          data = Uri.parse(uriString)
          putExtra("overlay", true)
          putExtra("callerId", context.packageName)
        }
      )
      return
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

Tuỳ thuộc vào trạng thái mà getSdkStatus() trả về, bạn có thể hướng dẫn người dùng cài đặt hoặc cập nhật Health Connect từ Cửa hàng Google Play nếu cần.

Các quyền bắt buộc

Quyền truy cập vào các bước được bảo vệ bằng các quyền sau:

  • android.permission.health.READ_STEPS
  • android.permission.health.WRITE_STEPS

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

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

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

Để đọc các bước, bạn cần yêu cầu các quyền sau:

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

Yêu cầu người dùng cấp quyền

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(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 định kỳ các quyền đã cấp và xử lý các tình huống khi mất quyền.

Thông tin có trong bản ghi Bước

Mỗi StepsRecord đều chứa những thông tin sau:

  • count: Số bước đã đi trong khoảng thời gian, dưới dạng Long.
  • startTime: Thời gian bắt đầu của khoảng thời gian đo.
  • endTime: Thời gian kết thúc của khoảng thời gian đo lường.
  • startZoneOffset: Giá trị chênh lệch múi giờ cho thời gian bắt đầu.
  • endZoneOffset: Giá trị chênh lệch múi giờ cho thời gian kết thúc.

Các phép tổng hợp được hỗ trợ

Các giá trị tổng hợp sau đây có sẵn cho StepsRecord:

Các giá trị tổng hợp sau đây có sẵn cho StepsCadenceRecord:

Ví dụ về cách sử dụng

Các phần sau đây cho biết cách đọc và ghi dữ liệu StepsRecord.

Ghi dữ liệu về số bước

Ứng dụng của bạn có thể ghi dữ liệu số bước bằng cách chèn các thực thể StepsRecord. Ví dụ sau đây cho thấy cách ghi lại 1.000 bước mà người dùng đã thực hiện:

suspend fun writeStepsData(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant,
    startZoneOffset: ZoneOffset,
    endZoneOffset: ZoneOffset
) {
    try {
        val stepsRecord = StepsRecord(
            startTime = startTime,
            startZoneOffset = startZoneOffset,
            endTime = endTime,
            endZoneOffset = endZoneOffset,
            count = 1000
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling
    }
}

Đọc dữ liệu tổng hợp

Cách phổ biến nhất để đọc dữ liệu về số bước là tổng hợp tổng số bước trong một khoảng thời gian. Ví dụ sau đây minh hoạ cách đọc tổng số bước của một người dùng trong một khoảng thời gian nhất định:

suspend fun readStepsAggregate(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Đọc dữ liệu thô

Ví dụ sau đây cho thấy cách đọc dữ liệu StepsRecord thô trong khoảng thời gian bắt đầu và kết thúc:

suspend fun readStepsRaw(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each record
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}