ติดตามขั้นตอน

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

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

อ่านขั้นตอนสำหรับอุปกรณ์เคลื่อนที่

เมื่อใช้ Android 14 (ระดับ API 34) และ SDK Extension เวอร์ชัน 20 ขึ้นไป Health Connect จะนับก้าวในอุปกรณ์ หากแอปใดได้รับสิทธิ์ READ_STEPS แล้ว Health Connect จะเริ่มบันทึกจำนวนก้าวจากอุปกรณ์ที่ใช้ Android และผู้ใช้จะเห็นข้อมูลจำนวนก้าวที่เพิ่มลงในรายการจำนวนก้าวของ Health Connect โดยอัตโนมัติ

หากต้องการตรวจสอบว่าการนับก้าวในอุปกรณ์พร้อมใช้งานหรือไม่ ให้ยืนยันว่าอุปกรณ์ใช้ Android 14 (ระดับ API 34) และมีส่วนขยาย SDK เวอร์ชัน 20 เป็นอย่างน้อย

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

หากแอปของคุณอ่านจำนวนก้าวรวมโดยใช้ aggregate และไม่ได้กรองตาม DataOrigin ระบบจะรวมจำนวนก้าวในอุปกรณ์ไว้ในยอดรวมโดยอัตโนมัติ และไม่จำเป็นต้องทำการเปลี่ยนแปลงใดๆ สำหรับการอัปเดตในเดือนมิถุนายน 2026

การเปลี่ยนแปลงการระบุแหล่งที่มาสำหรับขั้นตอนในอุปกรณ์

ตั้งแต่การอัปเดตในเดือนมิถุนายน 2026 เป็นต้นไป จำนวนก้าวที่ Health Connect ติดตามโดยตรงจะมาจากชื่อแพ็กเกจสังเคราะห์ (SPN) เช่น com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e

ก่อนหน้านี้ ขั้นตอนในตัวจะมาจากชื่อแพ็กเกจ android ข้อมูลจำนวนก้าวที่ผ่านมาซึ่งบันทึกไว้ก่อนเดือนมิถุนายน 2026 จะยังคงใช้ชื่อแพ็กเกจ android

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

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

คำถามเกี่ยวกับขั้นตอนในอุปกรณ์

เนื่องจาก SPN มีขอบเขตและเจาะจงอุปกรณ์ คุณจึงต้องไม่ฮาร์ดโค้ดค่า SPN แต่ให้ใช้ API getCurrentDeviceDataSource เพื่อดึงข้อมูล SPN สำหรับอุปกรณ์ปัจจุบันแทน

แม้ว่าการนับก้าวในอุปกรณ์จะต้องใช้ SDK Extension เวอร์ชัน 20 ขึ้นไป แต่ getCurrentDeviceDataSource() API จะพร้อมใช้งานใน Android 14 (ระดับ API 34) ที่มี SDK Extension เวอร์ชัน 22 ขึ้นไป หากต้องการใช้ API นี้ ให้ตั้งค่า compileSdkExtension เป็น 22 ขึ้นไปในไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ดังนี้

Kotlin

android {
    compileSdk = 35
    compileSdkExtension = 22
}

ดึงดูด

android {
    compileSdk 35
    compileSdkExtension 22
}

getCurrentDeviceDataSource() API ยังไม่พร้อมใช้งานในคลัง Jetpack ของ Health Connect ตัวอย่างต่อไปนี้ใช้ API ของเฟรมเวิร์ก Android ซึ่งต้องใช้ Callback Executor และ OutcomeReceiver

import android.content.Context
import android.health.connect.DeviceDataSource
import android.health.connect.HealthConnectException
import android.health.connect.HealthConnectManager
import android.os.OutcomeReceiver

val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)
healthConnectManager?.getCurrentDeviceDataSource(
    context.mainExecutor,
    object : OutcomeReceiver<DeviceDataSource, HealthConnectException> {
        override fun onResult(result: DeviceDataSource) {
            val currentDeviceSpn = result.deviceDataOrigin.packageName
        }

        override fun onError(error: HealthConnectException) {
            // Handle error
        }
    }
)

หากแอปของคุณต้องการอ่านจำนวนก้าวในอุปกรณ์ หรือหากแสดงข้อมูลจำนวนก้าวที่แยกตามแอปพลิเคชันหรืออุปกรณ์ต้นทาง คุณต้องค้นหาบันทึกที่ DataOrigin เป็น android หรือตรงกับ SPN ของอุปกรณ์ หากแอปแสดงการระบุแหล่งที่มาของข้อมูลจำนวนก้าว ให้ใช้ metadata.device เพื่อระบุอุปกรณ์ต้นทางสำหรับแต่ละบันทึก สำหรับขั้นตอนในอุปกรณ์ที่ระบุโดย SPN ในข้อมูลรวม คุณสามารถใช้ข้อมูลเมตาของอุปกรณ์ เช่น model หรือ manufacturer จาก DeviceDataSource สำหรับการระบุแหล่งที่มา หรือใช้ป้ายกำกับทั่วไป เช่น "โทรศัพท์ของคุณ" สำหรับขั้นตอนในอุปกรณ์

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

import android.content.Context
import android.health.connect.DeviceDataSource
import android.health.connect.HealthConnectException
import android.health.connect.HealthConnectManager
import android.os.Build
import android.os.OutcomeReceiver
import android.os.ext.SdkExtensions
import androidx.health.connect.client.HealthConnectClient
import androidx.health.connect.client.records.StepsRecord
import androidx.health.connect.client.records.metadata.DataOrigin
import androidx.health.connect.client.request.AggregateRequest
import androidx.health.connect.client.time.TimeRangeFilter
import java.time.Instant
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException
import kotlinx.coroutines.suspendCancellableCoroutine

suspend fun readDeviceStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    context: Context,
    startTime: Instant,
    endTime: Instant
) {
    // 1. Check if SDK Extension 22+ is available for getCurrentDeviceDataSource()
    val isDataSourceApiAvailable =
        Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
            SdkExtensions.getExtensionVersion(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) >= 22

    try {
        val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)

        // 2. Safely fetch the package name only if the API is available
        val currentDeviceSpn = if (isDataSourceApiAvailable && healthConnectManager != null) {
            suspendCancellableCoroutine { continuation ->
                healthConnectManager.getCurrentDeviceDataSource(
                    context.mainExecutor,
                    object : OutcomeReceiver<DeviceDataSource, HealthConnectException> {
                        override fun onResult(result: DeviceDataSource) {
                            continuation.resume(result.deviceDataOrigin.packageName)
                        }

                        override fun onError(error: HealthConnectException) {
                            continuation.resumeWithException(error)
                        }
                    }
                )
            }
        } else {
            null
        }

        val dataOriginFilters = mutableSetOf(DataOrigin("android"))

        // 3. Explicit null-safety check using .let
        currentDeviceSpn?.let {
            dataOriginFilters.add(DataOrigin(it))
        }

        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = dataOriginFilters
            )
        )

        val stepCount = response[StepsRecord.COUNT_TOTAL]

    } catch (e: Exception) {
        // Now this catch block only handles actual runtime exceptions,
        // rather than Errors from missing methods.
    }
}

การนับก้าวในอุปกรณ์

  • การใช้งานเซ็นเซอร์: Health Connect ใช้เซ็นเซอร์ TYPE_STEP_COUNTER จาก SensorManager เซ็นเซอร์นี้ได้รับการเพิ่มประสิทธิภาพให้ใช้พลังงานต่ำ จึงเหมาะอย่างยิ่งสำหรับการติดตามจำนวนก้าวในเบื้องหลังอย่างต่อเนื่อง
  • ความละเอียดของข้อมูล: โดยปกติแล้ว ระบบจะจัดกลุ่มข้อมูลจำนวนก้าวและเขียนลงในฐานข้อมูล Health Connect ไม่เกิน 1 ครั้งต่อนาทีเพื่อประหยัดแบตเตอรี่
  • การระบุแหล่งที่มา: ขั้นตอนที่บันทึกโดยฟีเจอร์นี้ก่อนเดือนมิถุนายน 2026 จะระบุแหล่งที่มาเป็นชื่อแพ็กเกจ android ใน DataOrigin หลังจากวันที่นี้ ระบบจะระบุแหล่งที่มาของ Conversion เป็น SPN เฉพาะอุปกรณ์ ดูการเปลี่ยนแปลงการระบุแหล่งที่มาสำหรับขั้นตอนในอุปกรณ์
  • การเปิดใช้งาน: กลไกการนับก้าวในอุปกรณ์จะทำงานก็ต่อเมื่อแอปพลิเคชันอย่างน้อย 1 แอปในอุปกรณ์ได้รับสิทธิ์ READ_STEPS ภายใน Health Connect

ตรวจสอบความพร้อมใช้งานของ Health Connect

ก่อนพยายามใช้ Health Connect แอปของคุณควรยืนยันว่า Health Connect พร้อมใช้งานในอุปกรณ์ของผู้ใช้ Health Connect อาจไม่ได้ติดตั้งไว้ล่วงหน้าในอุปกรณ์บางเครื่องหรืออาจปิดใช้อยู่ คุณตรวจสอบความพร้อมให้บริการได้โดยใช้เมธอด HealthConnectClient.getSdkStatus()

วิธีตรวจสอบความพร้อมใช้งานของ Health Connect

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata"
    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
}

คุณสามารถแนะนำให้ผู้ใช้ติดตั้งหรืออัปเดต Health Connect จาก Google Play Store ได้หากจำเป็น ทั้งนี้ขึ้นอยู่กับสถานะที่ getSdkStatus() แสดงผล

สิทธิ์ที่จำเป็น

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

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

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

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

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

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

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

ขอสิทธิ์จากผู้ใช้

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

val permissions =
    setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::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.") }
    }
}
เนื่องจากผู้ใช้สามารถให้หรือเพิกถอนสิทธิ์ได้ทุกเมื่อ แอปของคุณจึงต้องตรวจสอบสิทธิ์ทุกครั้งก่อนใช้งานและจัดการสถานการณ์ที่สิทธิ์หายไป

ข้อมูลที่รวมอยู่ในบันทึกจำนวนก้าว

StepsRecord แต่ละรายการจะมีข้อมูลต่อไปนี้

  • count: จำนวนก้าวที่เดินในช่วงเวลาหนึ่งๆ ในรูปแบบ Long
  • startTime: เวลาเริ่มต้นของช่วงการวัด
  • endTime: เวลาสิ้นสุดของช่วงการวัด
  • startZoneOffset: ออฟเซ็ตเขตเวลาสำหรับเวลาเริ่มต้น
  • endZoneOffset: ออฟเซ็ตเขตเวลาสำหรับเวลาสิ้นสุด

การรวมที่รองรับ

ค่ารวมต่อไปนี้ใช้ได้กับ StepsRecord

ค่ารวมต่อไปนี้ใช้ได้กับ StepsCadenceRecord

ตัวอย่างการใช้

ส่วนต่อไปนี้จะแสดงวิธีอ่านและเขียนข้อมูล StepsRecord

เขียนข้อมูลจำนวนก้าว

แอปของคุณสามารถเขียนข้อมูลจำนวนก้าวได้โดยการแทรกอินสแตนซ์ StepsRecord ตัวอย่างต่อไปนี้แสดงวิธีบันทึกการเดิน 1,000 ก้าวของผู้ใช้

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

อ่านข้อมูลรวม

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

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}

อ่านข้อมูลดิบ

ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูล StepsRecord ดิบระหว่างเวลาเริ่มต้นและเวลาสิ้นสุด

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        StepsRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}