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

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

อ่านข้อมูลจำนวนก้าวในอุปกรณ์เคลื่อนที่

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

หากต้องการตรวจสอบว่าการนับก้าวในอุปกรณ์พร้อมใช้งานหรือไม่ ให้ตรวจสอบว่าอุปกรณ์ ใช้ Android 14 (ระดับ API 34) และมี SDK Extension เวอร์ชัน 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 แบบถาวร แต่ให้ใช้ getCurrentDeviceDataSource() API เพื่อดึงข้อมูล SPN สำหรับอุปกรณ์ปัจจุบันแทน

แม้ว่าการนับก้าวในอุปกรณ์จะต้องใช้ SDK Extensions เวอร์ชัน 20 ขึ้นไป แต่ getCurrentDeviceDataSource() API ก็พร้อมใช้งานใน Android 14 (ระดับ API 34) ที่มี SDK Extensions เวอร์ชัน 11 ขึ้นไป

getCurrentDeviceDataSource() API ยังไม่พร้อมใช้งานในไลบรารี Jetpack ของ Health Connect ตัวอย่างต่อไปนี้ใช้ Android Framework API แทน 

import android.content.Context
import android.health.connect.HealthConnectManager

val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)
val deviceDataSource = healthConnectManager?.getCurrentDeviceDataSource()
val currentDeviceSpn = deviceDataSource?.deviceDataOrigin?.packageName

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

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

import android.content.Context
import android.health.connect.HealthConnectManager
import android.os.Build
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

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

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

        // 2. Safely fetch the package name only if API is available and data exists
        val currentDeviceSpn = if (isDataSourceApiAvailable) {
            healthConnectManager?.getCurrentDeviceDataSource()?.deviceDataOrigin?.packageName
        } 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 หลังจากวันที่ดังกล่าว ระบบจะ ระบุแหล่งที่มาเป็น 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" // 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
}

คุณสามารถแนะนำให้ผู้ใช้ติดตั้งหรืออัปเดต 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 ก่อน

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

ใช้ getGrantedPermissions เพื่อดูว่าแอปของคุณได้รับสิทธิ์ที่จำเป็นแล้วหรือไม่ หากไม่มี ให้ใช้ createRequestPermissionResultContract เพื่อขอสิทธิ์เหล่านั้น ซึ่งจะแสดงหน้าจอขอสิทธิ์ของ 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)
  }
}

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

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

แต่ละ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(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
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 */
}