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

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

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

ใน 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

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

หากแอปต้องอ่านจำนวนก้าวในอุปกรณ์ หรือหากแอปแสดงข้อมูลจำนวนก้าว ที่แบ่งตามแอปพลิเคชันหรืออุปกรณ์แหล่งที่มา คุณสามารถค้นหาบันทึก ที่ DataOrigin เป็น android ได้ หากแอปแสดงการระบุแหล่งที่มาสำหรับข้อมูลขั้นตอน คุณควรระบุแหล่งที่มาของข้อมูลจากแพ็กเกจ Android ไปยังอุปกรณ์ปัจจุบัน คุณทำได้โดยใช้ป้ายกำกับ เช่น "โทรศัพท์ของคุณ" ดึงข้อมูลชื่ออุปกรณ์ด้วย Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) หรือตรวจสอบฟิลด์ Device ในข้อมูลเมตาของระเบียน

ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูลจำนวนก้าวรวมในอุปกรณ์เคลื่อนที่โดย กรองต้นทางของข้อมูล 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
    }
}

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

เจาะลึกรายละเอียดเพิ่มเติมเกี่ยวกับฟีเจอร์การนับก้าวบนอุปกรณ์

  • การใช้เซ็นเซอร์: Health Connect ใช้เซ็นเซอร์ TYPE_STEP_COUNTER จาก SensorManager เซ็นเซอร์นี้ได้รับการเพิ่มประสิทธิภาพเพื่อการใช้พลังงานต่ำ จึงเหมาะสำหรับการติดตามจำนวนก้าวอย่างต่อเนื่องในเบื้องหลัง
  • ระดับความละเอียดของข้อมูล: โดยทั่วไปแล้ว ระบบจะจัดกลุ่มข้อมูลจำนวนก้าวและเขียนลงในฐานข้อมูล Health Connect ไม่บ่อยกว่า 1 ครั้งต่อนาทีเพื่อประหยัดแบตเตอรี่
  • การระบุแหล่งที่มา: ดังที่กล่าวไว้ก่อนหน้านี้ ขั้นตอนทั้งหมดที่บันทึกโดยฟีเจอร์ในอุปกรณ์นี้จะได้รับการระบุแหล่งที่มาเป็นชื่อแพ็กเกจ android ใน DataOrigin
  • การเปิดใช้งาน: กลไกการนับก้าวในอุปกรณ์จะทำงานเมื่อแอปพลิเคชันอย่างน้อย 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 ก้าว

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
    }
}

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

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

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
    }
}

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

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

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
    }
}