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
แต่ให้ใช้ 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 ตัวอย่างต่อไปนี้ใช้ Android Framework API
ซึ่งต้องใช้ 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หลังจากวันที่ดังกล่าว ระบบจะ ระบุแหล่งที่มาเป็น 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_STEPSandroid.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>
ขอสิทธิ์จากผู้ใช้
หลังจากสร้างอินสแตนซ์ไคลเอ็นต์แล้ว แอปของคุณต้องขอสิทธิ์จากผู้ใช้ ต้องอนุญาตให้ผู้ใช้ให้หรือปฏิเสธสิทธิ์ได้ทุกเมื่อ โดยให้สร้างชุดสิทธิ์สำหรับประเภทข้อมูลที่จำเป็น ตรวจสอบว่าได้ประกาศสิทธิ์ในชุดไว้ใน Android manifest ก่อน
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: จำนวนก้าวที่เดินในช่วงเวลาที่กำหนดเป็นLongstartTime: เวลาเริ่มต้นของช่วงการวัด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 */ }